Initial Commit
This commit is contained in:
@@ -0,0 +1,79 @@
|
||||
# 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`.
|
||||
62
openspec/changes/enterprise-api-plugin-file-upload/tasks.md
Normal file
62
openspec/changes/enterprise-api-plugin-file-upload/tasks.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# Tasks: enterprise-api-plugin-file-upload
|
||||
|
||||
**Change ID**: enterprise-api-plugin-file-upload
|
||||
**Package**: `@suaveplan/api-plugin-file-upload`
|
||||
**Target path**: `api/data/api-plugin-file-upload`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/api`, `@suaveplan/api-shared`, `@suaveplan/api-plugin-auth`, `@suaveplan/api-plugin-database`, `@suaveplan/mime`, `@suaveplan/exif`, `@suaveplan/audio-metadata`, `@suaveplan/compress-image`, `@suaveplan/events`, `@suaveplan/rate-limiter`, `@suaveplan/error`
|
||||
|
||||
---
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## 1. Scaffold + types + errors + events
|
||||
|
||||
- [ ] Create directory; `package.json` v0.0.0; standard tooling.
|
||||
- [ ] Types: `FileRecord`, `ChunkedUpload`, `FileStorageAdapter`, `FileUploadPluginConfig` (Zod). Allowed MIME types config.
|
||||
- [ ] Errors: 6-code union + registration. Test + doc.
|
||||
- [ ] Events: `FileUploadEventMap` (file:uploaded, file:quarantined, file:approved, file:deleted).
|
||||
|
||||
---
|
||||
|
||||
## 2. SurrealQL
|
||||
|
||||
- [ ] `file_record.surql` (key, mimeType, size, status [pending|approved|quarantined|deleted], uploadedBy, tenantId, metadata jsonb), `chunked_upload.surql`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Adapter port
|
||||
|
||||
- [ ] `src/adapters/storage.port.ts` — `FileStorageAdapter` interface. Local-disk default implementation for dev. Test + doc.
|
||||
|
||||
---
|
||||
|
||||
## 4. Services
|
||||
|
||||
- [ ] **UploadService**: `uploadSingle(stream, meta)` — MIME validation, size check, store via adapter, extract metadata. `initiateChunked`, `uploadPart`, `completeChunked`. Rate-limited. Test + doc.
|
||||
- [ ] **MetadataService**: dispatch to `@suaveplan/exif` for images, `@suaveplan/audio-metadata` for audio, no-op otherwise. Test + doc.
|
||||
- [ ] **LifecycleService**: `approveFile`, `quarantineFile`, `deleteFile`, `getFile`, `listFiles`, `getSignedDownloadUrl` (TTL). Test + doc.
|
||||
|
||||
---
|
||||
|
||||
## 5. Routes
|
||||
|
||||
- [ ] `POST /files` — `requireAuth` + rate-limit; single upload.
|
||||
- [ ] `GET /files/:id` — `requireAuth`.
|
||||
- [ ] `GET /files/:id/download` — signed URL check or direct stream.
|
||||
- [ ] `DELETE /files/:id` — `requireAuth` + audit.
|
||||
- [ ] Chunked: initiate, upload part, complete — `requireAuth` + rate-limit.
|
||||
- [ ] Route `.test.ts` + `.md`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Plugin factory + integration tests + publish
|
||||
|
||||
- [ ] `createFileUploadPlugin(storageAdapter, config?)`: `definePlugin`, `dependencies: ["database", "auth"]`, `migrationsPath: "./surql"`.
|
||||
- [ ] Integration: upload file → extract metadata → download → delete (real SurrealDB + local storage adapter).
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-file-upload` — green; 100% coverage.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/api-plugin-file-upload`.
|
||||
- [ ] Archive → `openspec/archive/2026-04-24-enterprise-api-plugin-file-upload/`.
|
||||
Reference in New Issue
Block a user