80 lines
3.1 KiB
Markdown
80 lines
3.1 KiB
Markdown
# OpenSpec Change: enterprise-api-plugin-file-upload
|
|
|
|
- **Change ID**: enterprise-api-plugin-file-upload
|
|
- **Package**: `@suaveplan/api-plugin-file-upload`
|
|
- **Category**: api/data
|
|
- **Target path**: `api/data/api-plugin-file-upload`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-plugin-file-upload.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/api-plugin-file-upload` on the genesis branch from scratch at enterprise quality. File upload and management plugin: multipart upload (single + chunked), MIME validation via `@suaveplan/mime`, virus-scan hook, pluggable storage backend (`StorageAdapter` — local disk, S3-compatible via `@suaveplan/storage-s3`), metadata extraction (images via `@suaveplan/exif`, audio via `@suaveplan/audio-metadata`), signed download URL generation, image compression via `@suaveplan/compress-image`, and file lifecycle management (quarantine, approve, delete). Routes under `/files`. Per-table SurrealQL. Events: `file:uploaded`, `file:approved`, `file:deleted`.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/api` (`workspace:^`) | `definePlugin` |
|
|
| `@suaveplan/api-shared` (`workspace:^`) | Helpers |
|
|
| `@suaveplan/api-plugin-auth` (`workspace:^`) | `requireAuth` |
|
|
| `@suaveplan/api-plugin-database` (`workspace:^`) | SurrealDB |
|
|
| `@suaveplan/mime` (`workspace:^`) | MIME type detection |
|
|
| `@suaveplan/exif` (`workspace:^`) | Image EXIF extraction |
|
|
| `@suaveplan/audio-metadata` (`workspace:^`) | Audio metadata extraction |
|
|
| `@suaveplan/compress-image` (`workspace:^`) | Image compression |
|
|
| `@suaveplan/events` (`workspace:^`) | Event bus |
|
|
| `@suaveplan/error` (`workspace:^`) | `FileUploadError` hierarchy |
|
|
| `@suaveplan/rate-limiter` (`workspace:^`) | Upload rate limits |
|
|
| `hono` + `@hono/zod-openapi` + `zod` | Routes |
|
|
| `@opentelemetry/api` | OTel |
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
```ts
|
|
function createFileUploadPlugin(storageAdapter: FileStorageAdapter, config?: FileUploadPluginConfig): PluginDescriptor
|
|
interface FileStorageAdapter { put(key, stream, meta): Promise<string>; get(key): Promise<ReadableStream>; delete(key): Promise<void>; getSignedUrl(key, ttlSeconds): Promise<string> }
|
|
// Routes: POST /files, GET /files/:id, GET /files/:id/download, DELETE /files/:id, POST /files/chunked/initiate, POST /files/chunked/:uploadId/part, POST /files/chunked/:uploadId/complete
|
|
```
|
|
|
|
### Error codes
|
|
|
|
```ts
|
|
type FileUploadErrorCode =
|
|
| "FILE_NOT_FOUND"
|
|
| "FILE_TYPE_NOT_ALLOWED"
|
|
| "FILE_TOO_LARGE"
|
|
| "FILE_QUARANTINED"
|
|
| "FILE_UPLOAD_INCOMPLETE"
|
|
| "FILE_STORAGE_ERROR"
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
api/data/api-plugin-file-upload/
|
|
package.json tsconfig.json vitest.config.ts
|
|
surql/ (file_record, chunked_upload tables)
|
|
src/
|
|
index.ts events.ts types/ errors/
|
|
adapters/storage.port.ts
|
|
services/upload/ services/metadata/ services/lifecycle/
|
|
routes/files/ routes/chunked/
|
|
tests/integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
Prerequisites: `@suaveplan/api`, `@suaveplan/api-plugin-auth`, `@suaveplan/api-plugin-database`, `@suaveplan/mime`, `@suaveplan/exif`, `@suaveplan/audio-metadata`, `@suaveplan/compress-image`.
|