Skip to content

Commit 08a04b7

Browse files
hotlonghotlong
authored
Merge pull request #383 from objectstack-ai/copilot/add-object-storage-protocol
2 parents fb2a4eb + ef0b1ac commit 08a04b7

28 files changed

+4355
-18
lines changed

‎content/docs/references/data/field.mdx‎

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ description: Field protocol schemas
1212
## TypeScript Usage
1313

1414
```typescript
15-
import { AddressSchema, CurrencyConfigSchema, CurrencyValueSchema, FieldSchema, FieldTypeSchema, LocationCoordinatesSchema, SelectOptionSchema, VectorConfigSchema } from '@objectstack/spec/data';
16-
import type { Address, CurrencyConfig, CurrencyValue, Field, FieldType, LocationCoordinates, SelectOption, VectorConfig } from '@objectstack/spec/data';
15+
import { AddressSchema, CurrencyConfigSchema, CurrencyValueSchema, FieldSchema, FieldTypeSchema, FileAttachmentConfigSchema, LocationCoordinatesSchema, SelectOptionSchema, VectorConfigSchema } from '@objectstack/spec/data';
16+
import type { Address, CurrencyConfig, CurrencyValue, Field, FieldType, FileAttachmentConfig, LocationCoordinates, SelectOption, VectorConfig } from '@objectstack/spec/data';
1717

1818
// Validate data
1919
const result = AddressSchema.parse(data);
@@ -110,6 +110,7 @@ const result = AddressSchema.parse(data);
110110
| **allowScanning** | `boolean` | optional | Enable camera scanning for barcode/QR code input |
111111
| **currencyConfig** | `object` | optional | Configuration for currency field type |
112112
| **vectorConfig** | `object` | optional | Configuration for vector field type (AI/ML embeddings) |
113+
| **fileAttachmentConfig** | `object` | optional | Configuration for file and attachment field types |
113114
| **hidden** | `boolean` | optional | Hidden from default UI |
114115
| **readonly** | `boolean` | optional | Read-only in UI |
115116
| **encryption** | `boolean` | optional | Encrypt at rest |
@@ -169,6 +170,39 @@ const result = AddressSchema.parse(data);
169170

170171
---
171172

173+
## FileAttachmentConfig
174+
175+
### Properties
176+
177+
| Property | Type | Required | Description |
178+
| :--- | :--- | :--- | :--- |
179+
| **minSize** | `number` | optional | Minimum file size in bytes |
180+
| **maxSize** | `number` | optional | Maximum file size in bytes (e.g., 10485760 = 10MB) |
181+
| **allowedTypes** | `string[]` | optional | Allowed file extensions (e.g., [".pdf", ".docx", ".jpg"]) |
182+
| **blockedTypes** | `string[]` | optional | Blocked file extensions (e.g., [".exe", ".bat", ".sh"]) |
183+
| **allowedMimeTypes** | `string[]` | optional | Allowed MIME types (e.g., ["image/jpeg", "application/pdf"]) |
184+
| **blockedMimeTypes** | `string[]` | optional | Blocked MIME types |
185+
| **virusScan** | `boolean` | optional | Enable virus scanning for uploaded files |
186+
| **virusScanProvider** | `Enum<'clamav' \| 'virustotal' \| 'metadefender' \| 'custom'>` | optional | Virus scanning service provider |
187+
| **virusScanOnUpload** | `boolean` | optional | Scan files immediately on upload |
188+
| **quarantineOnThreat** | `boolean` | optional | Quarantine files if threat detected |
189+
| **storageProvider** | `string` | optional | Object storage provider name (references ObjectStorageConfig) |
190+
| **storageBucket** | `string` | optional | Target bucket name |
191+
| **storagePrefix** | `string` | optional | Storage path prefix (e.g., "uploads/documents/") |
192+
| **imageValidation** | `object` | optional | Image-specific validation rules |
193+
| **allowMultiple** | `boolean` | optional | Allow multiple file uploads (overrides field.multiple) |
194+
| **allowReplace** | `boolean` | optional | Allow replacing existing files |
195+
| **allowDelete** | `boolean` | optional | Allow deleting uploaded files |
196+
| **requireUpload** | `boolean` | optional | Require at least one file when field is required |
197+
| **extractMetadata** | `boolean` | optional | Extract file metadata (name, size, type, etc.) |
198+
| **extractText** | `boolean` | optional | Extract text content from documents (OCR/parsing) |
199+
| **versioningEnabled** | `boolean` | optional | Keep previous versions of replaced files |
200+
| **maxVersions** | `number` | optional | Maximum number of versions to retain |
201+
| **publicRead** | `boolean` | optional | Allow public read access to uploaded files |
202+
| **presignedUrlExpiry** | `number` | optional | Presigned URL expiration in seconds (default: 1 hour) |
203+
204+
---
205+
172206
## LocationCoordinates
173207

174208
### Properties

‎content/docs/references/integration/misc.mdx‎

Lines changed: 2 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@ description: Misc protocol schemas
1212
## TypeScript Usage
1313

1414
```typescript
15-
import { AckModeSchema, ApiVersionConfigSchema, CdcConfigSchema, ConsumerConfigSchema, DatabaseConnectorSchema, DatabasePoolConfigSchema, DatabaseProviderSchema, DatabaseTableSchema, DeliveryGuaranteeSchema, DlqConfigSchema, FileAccessPatternSchema, FileFilterConfigSchema, FileMetadataConfigSchema, FileStorageConnectorSchema, FileStorageProviderSchema, FileVersioningConfigSchema, MessageFormatSchema, MessageQueueConnectorSchema, MessageQueueProviderSchema, MultipartUploadConfigSchema, ProducerConfigSchema, SaasConnectorSchema, SaasObjectTypeSchema, SaasProviderSchema, SslConfigSchema, StorageBucketSchema, TopicQueueSchema } from '@objectstack/spec/integration';
16-
import type { AckMode, ApiVersionConfig, CdcConfig, ConsumerConfig, DatabaseConnector, DatabasePoolConfig, DatabaseProvider, DatabaseTable, DeliveryGuarantee, DlqConfig, FileAccessPattern, FileFilterConfig, FileMetadataConfig, FileStorageConnector, FileStorageProvider, FileVersioningConfig, MessageFormat, MessageQueueConnector, MessageQueueProvider, MultipartUploadConfig, ProducerConfig, SaasConnector, SaasObjectType, SaasProvider, SslConfig, StorageBucket, TopicQueue } from '@objectstack/spec/integration';
15+
import { AckModeSchema, ApiVersionConfigSchema, CdcConfigSchema, ConsumerConfigSchema, DatabaseConnectorSchema, DatabasePoolConfigSchema, DatabaseProviderSchema, DatabaseTableSchema, DeliveryGuaranteeSchema, DlqConfigSchema, FileAccessPatternSchema, FileFilterConfigSchema, FileMetadataConfigSchema, FileStorageConnectorSchema, FileStorageProviderSchema, FileVersioningConfigSchema, MessageFormatSchema, MessageQueueConnectorSchema, MessageQueueProviderSchema, ProducerConfigSchema, SaasConnectorSchema, SaasObjectTypeSchema, SaasProviderSchema, SslConfigSchema, StorageBucketSchema, TopicQueueSchema } from '@objectstack/spec/integration';
16+
import type { AckMode, ApiVersionConfig, CdcConfig, ConsumerConfig, DatabaseConnector, DatabasePoolConfig, DatabaseProvider, DatabaseTable, DeliveryGuarantee, DlqConfig, FileAccessPattern, FileFilterConfig, FileMetadataConfig, FileStorageConnector, FileStorageProvider, FileVersioningConfig, MessageFormat, MessageQueueConnector, MessageQueueProvider, ProducerConfig, SaasConnector, SaasObjectType, SaasProvider, SslConfig, StorageBucket, TopicQueue } from '@objectstack/spec/integration';
1717

1818
// Validate data
1919
const result = AckModeSchema.parse(data);
@@ -374,19 +374,6 @@ Message queue provider type
374374

375375
---
376376

377-
## MultipartUploadConfig
378-
379-
### Properties
380-
381-
| Property | Type | Required | Description |
382-
| :--- | :--- | :--- | :--- |
383-
| **enabled** | `boolean` | optional | Enable multipart uploads |
384-
| **partSize** | `number` | optional | Part size in bytes (min 5MB) |
385-
| **maxConcurrentParts** | `number` | optional | Maximum concurrent part uploads |
386-
| **threshold** | `number` | optional | File size threshold for multipart upload in bytes |
387-
388-
---
389-
390377
## ProducerConfig
391378

392379
### Properties

‎content/docs/references/integration/object-storage.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: Object Storage
3+
description: Object Storage protocol schemas
4+
---
5+
6+
# Object Storage
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/integration/object-storage.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { MultipartUploadConfigSchema } from '@objectstack/spec/integration';
16+
import type { MultipartUploadConfig } from '@objectstack/spec/integration';
17+
18+
// Validate data
19+
const result = MultipartUploadConfigSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## MultipartUploadConfig
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **enabled** | `boolean` | optional | Enable multipart uploads |
31+
| **partSize** | `number` | optional | Part size in bytes (min 5MB) |
32+
| **maxConcurrentParts** | `number` | optional | Maximum concurrent part uploads |
33+
| **threshold** | `number` | optional | File size threshold for multipart upload in bytes |
34+

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ This section contains all protocol schemas for the system layer of ObjectStack.
2121
<Card href="./logging" title="Logging" description="Source: packages/spec/src/system/logging.zod.ts" />
2222
<Card href="./manifest" title="Manifest" description="Source: packages/spec/src/system/manifest.zod.ts" />
2323
<Card href="./metrics" title="Metrics" description="Source: packages/spec/src/system/metrics.zod.ts" />
24+
<Card href="./object-storage" title="Object Storage" description="Source: packages/spec/src/system/object-storage.zod.ts" />
2425
<Card href="./plugin" title="Plugin" description="Source: packages/spec/src/system/plugin.zod.ts" />
2526
<Card href="./plugin-capability" title="Plugin Capability" description="Source: packages/spec/src/system/plugin-capability.zod.ts" />
2627
<Card href="./scoped-storage" title="Scoped Storage" description="Source: packages/spec/src/system/scoped-storage.zod.ts" />

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
"logging",
1515
"manifest",
1616
"metrics",
17+
"object-storage",
1718
"plugin",
1819
"plugin-capability",
1920
"scoped-storage",

‎content/docs/references/system/object-storage.mdx‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
---
2+
title: Object Storage
3+
description: Object Storage protocol schemas
4+
---
5+
6+
# Object Storage
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/system/object-storage.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { AccessControlConfigSchema, BucketConfigSchema, LifecycleActionSchema, LifecyclePolicyConfigSchema, LifecyclePolicyRuleSchema, MultipartUploadConfigSchema, ObjectMetadataSchema, ObjectStorageConfigSchema, PresignedUrlConfigSchema, StorageAclSchema, StorageClassSchema, StorageConnectionSchema, StorageProviderSchema } from '@objectstack/spec/system';
16+
import type { AccessControlConfig, BucketConfig, LifecycleAction, LifecyclePolicyConfig, LifecyclePolicyRule, MultipartUploadConfig, ObjectMetadata, ObjectStorageConfig, PresignedUrlConfig, StorageAcl, StorageClass, StorageConnection, StorageProvider } from '@objectstack/spec/system';
17+
18+
// Validate data
19+
const result = AccessControlConfigSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## AccessControlConfig
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **acl** | `Enum<'private' \| 'public_read' \| 'public_read_write' \| 'authenticated_read' \| 'bucket_owner_read' \| 'bucket_owner_full_control'>` | optional | Default access control level |
31+
| **allowedOrigins** | `string[]` | optional | CORS allowed origins |
32+
| **allowedMethods** | `Enum<'GET' \| 'PUT' \| 'POST' \| 'DELETE' \| 'HEAD'>[]` | optional | CORS allowed HTTP methods |
33+
| **allowedHeaders** | `string[]` | optional | CORS allowed headers |
34+
| **exposeHeaders** | `string[]` | optional | CORS exposed headers |
35+
| **maxAge** | `number` | optional | CORS preflight cache duration in seconds |
36+
| **corsEnabled** | `boolean` | optional | Enable CORS configuration |
37+
| **publicAccess** | `object` | optional | Public access control |
38+
| **allowedIps** | `string[]` | optional | Allowed IP addresses/CIDR blocks |
39+
| **blockedIps** | `string[]` | optional | Blocked IP addresses/CIDR blocks |
40+
41+
---
42+
43+
## BucketConfig
44+
45+
### Properties
46+
47+
| Property | Type | Required | Description |
48+
| :--- | :--- | :--- | :--- |
49+
| **name** | `string` | ✅ | Bucket identifier in ObjectStack (snake_case) |
50+
| **label** | `string` | ✅ | Display label |
51+
| **bucketName** | `string` | ✅ | Actual bucket/container name in storage provider |
52+
| **region** | `string` | optional | Storage region (e.g., us-east-1, westus) |
53+
| **provider** | `Enum<'s3' \| 'azure_blob' \| 'gcs' \| 'minio' \| 'r2' \| 'spaces' \| 'wasabi' \| 'backblaze' \| 'local'>` | ✅ | Storage provider |
54+
| **endpoint** | `string` | optional | Custom endpoint URL (for S3-compatible providers) |
55+
| **pathStyle** | `boolean` | optional | Use path-style URLs (for S3-compatible providers) |
56+
| **versioning** | `boolean` | optional | Enable object versioning |
57+
| **encryption** | `object` | optional | Server-side encryption configuration |
58+
| **accessControl** | `object` | optional | Access control configuration |
59+
| **lifecyclePolicy** | `object` | optional | Lifecycle policy configuration |
60+
| **multipartConfig** | `object` | optional | Multipart upload configuration |
61+
| **tags** | `Record<string, string>` | optional | Bucket tags for organization |
62+
| **description** | `string` | optional | Bucket description |
63+
| **enabled** | `boolean` | optional | Enable this bucket |
64+
65+
---
66+
67+
## LifecycleAction
68+
69+
Lifecycle policy action type
70+
71+
### Allowed Values
72+
73+
* `transition`
74+
* `delete`
75+
* `abort`
76+
77+
---
78+
79+
## LifecyclePolicyConfig
80+
81+
### Properties
82+
83+
| Property | Type | Required | Description |
84+
| :--- | :--- | :--- | :--- |
85+
| **enabled** | `boolean` | optional | Enable lifecycle policies |
86+
| **rules** | `object[]` | optional | Lifecycle rules |
87+
88+
---
89+
90+
## LifecyclePolicyRule
91+
92+
### Properties
93+
94+
| Property | Type | Required | Description |
95+
| :--- | :--- | :--- | :--- |
96+
| **id** | `string` | ✅ | Rule identifier |
97+
| **enabled** | `boolean` | optional | Enable this rule |
98+
| **action** | `Enum<'transition' \| 'delete' \| 'abort'>` | ✅ | Action to perform |
99+
| **prefix** | `string` | optional | Object key prefix filter (e.g., "uploads/") |
100+
| **tags** | `Record<string, string>` | optional | Object tag filters |
101+
| **daysAfterCreation** | `number` | optional | Days after object creation |
102+
| **daysAfterModification** | `number` | optional | Days after last modification |
103+
| **targetStorageClass** | `Enum<'standard' \| 'intelligent' \| 'infrequent_access' \| 'glacier' \| 'deep_archive'>` | optional | Target storage class for transition action |
104+
105+
---
106+
107+
## MultipartUploadConfig
108+
109+
### Properties
110+
111+
| Property | Type | Required | Description |
112+
| :--- | :--- | :--- | :--- |
113+
| **enabled** | `boolean` | optional | Enable multipart uploads |
114+
| **partSize** | `number` | optional | Part size in bytes (min 5MB, max 5GB) |
115+
| **maxParts** | `number` | optional | Maximum number of parts (max 10,000) |
116+
| **threshold** | `number` | optional | File size threshold to trigger multipart upload (bytes) |
117+
| **maxConcurrent** | `number` | optional | Maximum concurrent part uploads |
118+
| **abortIncompleteAfterDays** | `number` | optional | Auto-abort incomplete uploads after N days |
119+
120+
---
121+
122+
## ObjectMetadata
123+
124+
### Properties
125+
126+
| Property | Type | Required | Description |
127+
| :--- | :--- | :--- | :--- |
128+
| **contentType** | `string` | ✅ | MIME type (e.g., image/jpeg, application/pdf) |
129+
| **contentLength** | `number` | ✅ | File size in bytes |
130+
| **contentEncoding** | `string` | optional | Content encoding (e.g., gzip) |
131+
| **contentDisposition** | `string` | optional | Content disposition header |
132+
| **contentLanguage** | `string` | optional | Content language |
133+
| **cacheControl** | `string` | optional | Cache control directives |
134+
| **etag** | `string` | optional | Entity tag for versioning/caching |
135+
| **lastModified** | `string` | optional | Last modification timestamp |
136+
| **versionId** | `string` | optional | Object version identifier |
137+
| **storageClass** | `Enum<'standard' \| 'intelligent' \| 'infrequent_access' \| 'glacier' \| 'deep_archive'>` | optional | Storage class/tier |
138+
| **encryption** | `object` | optional | Server-side encryption configuration |
139+
| **custom** | `Record<string, string>` | optional | Custom user-defined metadata |
140+
141+
---
142+
143+
## ObjectStorageConfig
144+
145+
### Properties
146+
147+
| Property | Type | Required | Description |
148+
| :--- | :--- | :--- | :--- |
149+
| **name** | `string` | ✅ | Storage configuration identifier |
150+
| **label** | `string` | ✅ | Display label |
151+
| **provider** | `Enum<'s3' \| 'azure_blob' \| 'gcs' \| 'minio' \| 'r2' \| 'spaces' \| 'wasabi' \| 'backblaze' \| 'local'>` | ✅ | Primary storage provider |
152+
| **connection** | `object` | ✅ | Connection credentials |
153+
| **buckets** | `object[]` | optional | Configured buckets |
154+
| **defaultBucket** | `string` | optional | Default bucket name for operations |
155+
| **enabled** | `boolean` | optional | Enable this storage configuration |
156+
| **description** | `string` | optional | Configuration description |
157+
158+
---
159+
160+
## PresignedUrlConfig
161+
162+
### Properties
163+
164+
| Property | Type | Required | Description |
165+
| :--- | :--- | :--- | :--- |
166+
| **operation** | `Enum<'get' \| 'put' \| 'delete' \| 'head'>` | ✅ | Allowed operation |
167+
| **expiresIn** | `number` | ✅ | Expiration time in seconds (max 7 days) |
168+
| **contentType** | `string` | optional | Required content type for PUT operations |
169+
| **maxSize** | `number` | optional | Maximum file size in bytes for PUT operations |
170+
| **responseContentType** | `string` | optional | Override content-type for GET operations |
171+
| **responseContentDisposition** | `string` | optional | Override content-disposition for GET operations |
172+
173+
---
174+
175+
## StorageAcl
176+
177+
Storage access control level
178+
179+
### Allowed Values
180+
181+
* `private`
182+
* `public_read`
183+
* `public_read_write`
184+
* `authenticated_read`
185+
* `bucket_owner_read`
186+
* `bucket_owner_full_control`
187+
188+
---
189+
190+
## StorageClass
191+
192+
Storage class/tier for cost optimization
193+
194+
### Allowed Values
195+
196+
* `standard`
197+
* `intelligent`
198+
* `infrequent_access`
199+
* `glacier`
200+
* `deep_archive`
201+
202+
---
203+
204+
## StorageConnection
205+
206+
### Properties
207+
208+
| Property | Type | Required | Description |
209+
| :--- | :--- | :--- | :--- |
210+
| **accessKeyId** | `string` | optional | AWS access key ID or MinIO access key |
211+
| **secretAccessKey** | `string` | optional | AWS secret access key or MinIO secret key |
212+
| **sessionToken** | `string` | optional | AWS session token for temporary credentials |
213+
| **accountName** | `string` | optional | Azure storage account name |
214+
| **accountKey** | `string` | optional | Azure storage account key |
215+
| **sasToken** | `string` | optional | Azure SAS token |
216+
| **projectId** | `string` | optional | GCP project ID |
217+
| **credentials** | `string` | optional | GCP service account credentials JSON |
218+
| **endpoint** | `string` | optional | Custom endpoint URL |
219+
| **region** | `string` | optional | Default region |
220+
| **useSSL** | `boolean` | optional | Use SSL/TLS for connections |
221+
| **timeout** | `number` | optional | Connection timeout in milliseconds |
222+
223+
---
224+
225+
## StorageProvider
226+
227+
Storage provider type
228+
229+
### Allowed Values
230+
231+
* `s3`
232+
* `azure_blob`
233+
* `gcs`
234+
* `minio`
235+
* `r2`
236+
* `spaces`
237+
* `wasabi`
238+
* `backblaze`
239+
* `local`
240+

0 commit comments

Comments
 (0)