Skip to content

Commit 4ff61b7

Browse files
hotlonghotlong
authored
Merge pull request #371 from objectstack-ai/copilot/add-graphql-schema-security
2 parents f56c419 + e359408 commit 4ff61b7

20 files changed

Lines changed: 4957 additions & 0 deletions

‎content/docs/references/api/graphql.mdx‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
---
2+
title: Graphql
3+
description: Graphql protocol schemas
4+
---
5+
6+
# Graphql
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/api/graphql.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { GraphQLConfigSchema, GraphQLDataLoaderConfigSchema, GraphQLDirectiveConfigSchema, GraphQLDirectiveLocationSchema, GraphQLMutationConfigSchema, GraphQLPersistedQuerySchema, GraphQLQueryComplexitySchema, GraphQLQueryConfigSchema, GraphQLQueryDepthLimitSchema, GraphQLRateLimitSchema, GraphQLResolverConfigSchema, GraphQLScalarTypeSchema, GraphQLSubscriptionConfigSchema, GraphQLTypeConfigSchema } from '@objectstack/spec/api';
16+
import type { GraphQLConfig, GraphQLDataLoaderConfig, GraphQLDirectiveConfig, GraphQLDirectiveLocation, GraphQLMutationConfig, GraphQLPersistedQuery, GraphQLQueryComplexity, GraphQLQueryConfig, GraphQLQueryDepthLimit, GraphQLRateLimit, GraphQLResolverConfig, GraphQLScalarType, GraphQLSubscriptionConfig, GraphQLTypeConfig } from '@objectstack/spec/api';
17+
18+
// Validate data
19+
const result = GraphQLConfigSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## GraphQLConfig
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **enabled** | `boolean` | optional | Enable GraphQL API |
31+
| **path** | `string` | optional | GraphQL endpoint path |
32+
| **playground** | `object` | optional | GraphQL Playground configuration |
33+
| **schema** | `object` | optional | Schema generation configuration |
34+
| **dataLoaders** | `object[]` | optional | DataLoader configurations |
35+
| **security** | `object` | optional | Security configuration |
36+
37+
---
38+
39+
## GraphQLDataLoaderConfig
40+
41+
### Properties
42+
43+
| Property | Type | Required | Description |
44+
| :--- | :--- | :--- | :--- |
45+
| **name** | `string` | ✅ | DataLoader name |
46+
| **source** | `string` | ✅ | Source object or datasource |
47+
| **batchFunction** | `object` | ✅ | Batch function configuration |
48+
| **cache** | `object` | optional | DataLoader caching |
49+
| **options** | `object` | optional | DataLoader options |
50+
51+
---
52+
53+
## GraphQLDirectiveConfig
54+
55+
### Properties
56+
57+
| Property | Type | Required | Description |
58+
| :--- | :--- | :--- | :--- |
59+
| **name** | `string` | ✅ | Directive name (camelCase) |
60+
| **description** | `string` | optional | Directive description |
61+
| **locations** | `Enum<'QUERY' \| 'MUTATION' \| 'SUBSCRIPTION' \| 'FIELD' \| 'FRAGMENT_DEFINITION' \| 'FRAGMENT_SPREAD' \| 'INLINE_FRAGMENT' \| 'VARIABLE_DEFINITION' \| 'SCHEMA' \| 'SCALAR' \| 'OBJECT' \| 'FIELD_DEFINITION' \| 'ARGUMENT_DEFINITION' \| 'INTERFACE' \| 'UNION' \| 'ENUM' \| 'ENUM_VALUE' \| 'INPUT_OBJECT' \| 'INPUT_FIELD_DEFINITION'>[]` | ✅ | Directive locations |
62+
| **args** | `Record<string, object>` | optional | Directive arguments |
63+
| **repeatable** | `boolean` | optional | Can be applied multiple times |
64+
| **implementation** | `object` | optional | Directive implementation |
65+
66+
---
67+
68+
## GraphQLDirectiveLocation
69+
70+
### Allowed Values
71+
72+
* `QUERY`
73+
* `MUTATION`
74+
* `SUBSCRIPTION`
75+
* `FIELD`
76+
* `FRAGMENT_DEFINITION`
77+
* `FRAGMENT_SPREAD`
78+
* `INLINE_FRAGMENT`
79+
* `VARIABLE_DEFINITION`
80+
* `SCHEMA`
81+
* `SCALAR`
82+
* `OBJECT`
83+
* `FIELD_DEFINITION`
84+
* `ARGUMENT_DEFINITION`
85+
* `INTERFACE`
86+
* `UNION`
87+
* `ENUM`
88+
* `ENUM_VALUE`
89+
* `INPUT_OBJECT`
90+
* `INPUT_FIELD_DEFINITION`
91+
92+
---
93+
94+
## GraphQLMutationConfig
95+
96+
### Properties
97+
98+
| Property | Type | Required | Description |
99+
| :--- | :--- | :--- | :--- |
100+
| **name** | `string` | ✅ | Mutation field name (camelCase recommended) |
101+
| **object** | `string` | ✅ | Source ObjectQL object name |
102+
| **type** | `Enum<'create' \| 'update' \| 'delete' \| 'upsert' \| 'custom'>` | ✅ | Mutation type |
103+
| **description** | `string` | optional | Mutation description |
104+
| **input** | `object` | optional | Input configuration |
105+
| **output** | `object` | optional | Output configuration |
106+
| **transaction** | `object` | optional | Transaction configuration |
107+
| **authRequired** | `boolean` | optional | Require authentication |
108+
| **permissions** | `string[]` | optional | Required permissions |
109+
| **hooks** | `object` | optional | Lifecycle hooks |
110+
111+
---
112+
113+
## GraphQLPersistedQuery
114+
115+
### Properties
116+
117+
| Property | Type | Required | Description |
118+
| :--- | :--- | :--- | :--- |
119+
| **enabled** | `boolean` | optional | Enable persisted queries |
120+
| **mode** | `Enum<'optional' \| 'required'>` | optional | Persisted query mode (optional: allow both, required: only persisted) |
121+
| **store** | `object` | optional | Query store configuration |
122+
| **apq** | `object` | optional | Automatic Persisted Queries configuration |
123+
| **allowlist** | `object` | optional | Query allow list configuration |
124+
| **security** | `object` | optional | Security configuration |
125+
126+
---
127+
128+
## GraphQLQueryComplexity
129+
130+
### Properties
131+
132+
| Property | Type | Required | Description |
133+
| :--- | :--- | :--- | :--- |
134+
| **enabled** | `boolean` | optional | Enable query complexity limiting |
135+
| **maxComplexity** | `integer` | optional | Maximum query complexity |
136+
| **defaultFieldComplexity** | `integer` | optional | Default complexity per field |
137+
| **fieldComplexity** | `Record<string, integer \| object>` | optional | Per-field complexity configuration |
138+
| **listMultiplier** | `number` | optional | Multiplier for list fields |
139+
| **onComplexityExceeded** | `Enum<'reject' \| 'log' \| 'warn'>` | optional | Action when complexity exceeded |
140+
| **errorMessage** | `string` | optional | Custom error message for complexity violations |
141+
142+
---
143+
144+
## GraphQLQueryConfig
145+
146+
### Properties
147+
148+
| Property | Type | Required | Description |
149+
| :--- | :--- | :--- | :--- |
150+
| **name** | `string` | ✅ | Query field name (camelCase recommended) |
151+
| **object** | `string` | ✅ | Source ObjectQL object name |
152+
| **type** | `Enum<'get' \| 'list' \| 'search'>` | ✅ | Query type |
153+
| **description** | `string` | optional | Query description |
154+
| **args** | `Record<string, object>` | optional | Query arguments |
155+
| **filtering** | `object` | optional | Filtering capabilities |
156+
| **sorting** | `object` | optional | Sorting capabilities |
157+
| **pagination** | `object` | optional | Pagination configuration |
158+
| **fields** | `object` | optional | Field selection configuration |
159+
| **authRequired** | `boolean` | optional | Require authentication |
160+
| **permissions** | `string[]` | optional | Required permissions |
161+
| **cache** | `object` | optional | Query caching |
162+
163+
---
164+
165+
## GraphQLQueryDepthLimit
166+
167+
### Properties
168+
169+
| Property | Type | Required | Description |
170+
| :--- | :--- | :--- | :--- |
171+
| **enabled** | `boolean` | optional | Enable query depth limiting |
172+
| **maxDepth** | `integer` | optional | Maximum query depth |
173+
| **ignoreFields** | `string[]` | optional | Fields excluded from depth calculation |
174+
| **onDepthExceeded** | `Enum<'reject' \| 'log' \| 'warn'>` | optional | Action when depth exceeded |
175+
| **errorMessage** | `string` | optional | Custom error message for depth violations |
176+
177+
---
178+
179+
## GraphQLRateLimit
180+
181+
### Properties
182+
183+
| Property | Type | Required | Description |
184+
| :--- | :--- | :--- | :--- |
185+
| **enabled** | `boolean` | optional | Enable rate limiting |
186+
| **strategy** | `Enum<'token_bucket' \| 'fixed_window' \| 'sliding_window' \| 'cost_based'>` | optional | Rate limiting strategy |
187+
| **global** | `object` | optional | Global rate limits |
188+
| **perUser** | `object` | optional | Per-user rate limits |
189+
| **costBased** | `object` | optional | Cost-based rate limiting |
190+
| **operations** | `Record<string, object>` | optional | Per-operation rate limits |
191+
| **onLimitExceeded** | `Enum<'reject' \| 'queue' \| 'log'>` | optional | Action when rate limit exceeded |
192+
| **errorMessage** | `string` | optional | Custom error message for rate limit violations |
193+
| **includeHeaders** | `boolean` | optional | Include rate limit headers in response |
194+
195+
---
196+
197+
## GraphQLResolverConfig
198+
199+
### Properties
200+
201+
| Property | Type | Required | Description |
202+
| :--- | :--- | :--- | :--- |
203+
| **path** | `string` | ✅ | Resolver path (Type.field) |
204+
| **type** | `Enum<'datasource' \| 'computed' \| 'script' \| 'proxy'>` | ✅ | Resolver implementation type |
205+
| **implementation** | `object` | optional | Implementation configuration |
206+
| **cache** | `object` | optional | Resolver caching |
207+
208+
---
209+
210+
## GraphQLScalarType
211+
212+
### Allowed Values
213+
214+
* `ID`
215+
* `String`
216+
* `Int`
217+
* `Float`
218+
* `Boolean`
219+
* `DateTime`
220+
* `Date`
221+
* `Time`
222+
* `JSON`
223+
* `JSONObject`
224+
* `Upload`
225+
* `URL`
226+
* `Email`
227+
* `PhoneNumber`
228+
* `Currency`
229+
* `Decimal`
230+
* `BigInt`
231+
* `Long`
232+
* `UUID`
233+
* `Base64`
234+
* `Void`
235+
236+
---
237+
238+
## GraphQLSubscriptionConfig
239+
240+
### Properties
241+
242+
| Property | Type | Required | Description |
243+
| :--- | :--- | :--- | :--- |
244+
| **name** | `string` | ✅ | Subscription field name (camelCase recommended) |
245+
| **object** | `string` | ✅ | Source ObjectQL object name |
246+
| **events** | `Enum<'created' \| 'updated' \| 'deleted' \| 'custom'>[]` | ✅ | Events to subscribe to |
247+
| **description** | `string` | optional | Subscription description |
248+
| **filter** | `object` | optional | Subscription filtering |
249+
| **payload** | `object` | optional | Payload configuration |
250+
| **authRequired** | `boolean` | optional | Require authentication |
251+
| **permissions** | `string[]` | optional | Required permissions |
252+
| **rateLimit** | `object` | optional | Subscription rate limiting |
253+
254+
---
255+
256+
## GraphQLTypeConfig
257+
258+
### Properties
259+
260+
| Property | Type | Required | Description |
261+
| :--- | :--- | :--- | :--- |
262+
| **name** | `string` | ✅ | GraphQL type name (PascalCase recommended) |
263+
| **object** | `string` | ✅ | Source ObjectQL object name |
264+
| **description** | `string` | optional | Type description |
265+
| **fields** | `object` | optional | Field configuration |
266+
| **interfaces** | `string[]` | optional | GraphQL interface names |
267+
| **isInterface** | `boolean` | optional | Define as GraphQL interface |
268+
| **directives** | `object[]` | optional | GraphQL directives |
269+

‎content/docs/references/api/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ This section contains all protocol schemas for the api layer of ObjectStack.
1111
<Card href="./contract" title="Contract" description="Source: packages/spec/src/api/contract.zod.ts" />
1212
<Card href="./discovery" title="Discovery" description="Source: packages/spec/src/api/discovery.zod.ts" />
1313
<Card href="./endpoint" title="Endpoint" description="Source: packages/spec/src/api/endpoint.zod.ts" />
14+
<Card href="./graphql" title="Graphql" description="Source: packages/spec/src/api/graphql.zod.ts" />
1415
<Card href="./odata" title="Odata" description="Source: packages/spec/src/api/odata.zod.ts" />
1516
<Card href="./realtime" title="Realtime" description="Source: packages/spec/src/api/realtime.zod.ts" />
1617
<Card href="./router" title="Router" description="Source: packages/spec/src/api/router.zod.ts" />

‎content/docs/references/api/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
"contract",
55
"discovery",
66
"endpoint",
7+
"graphql",
78
"odata",
89
"realtime",
910
"router"

0 commit comments

Comments
 (0)