58 lines
3.9 KiB
Markdown
58 lines
3.9 KiB
Markdown
# Drive — Spec Delta (drive-port)
|
|
|
|
## ADDED Requirements
|
|
|
|
### DRIVE-01 — Drive consumes `AbstractStorage` directly
|
|
|
|
`Drive` MUST accept any concrete `AbstractStorage` from `@suaveplan/storage` as its storage substrate. There MUST NOT be a separate `StorageAdapter` shim. Drive MUST narrow capabilities through a `DriveStorage` view that extends `AbstractStorage` with `id: string` and optional `capabilities?: { partialReads?, nativeStreams?, atomicWrites?, contentAddressable?, partialWrites?, requiresLifecycle? }` plus optional `connect?()`, `dispose?()`, `isConnected?()` lifecycle hooks.
|
|
|
|
**Verified by:** `src/drive/drive.spec-conformance.test.ts` (`DRIVE-01`).
|
|
|
|
### DRIVE-02 — `initialize()` is idempotent and ownership-tracking
|
|
|
|
`Drive.initialize()` MUST be idempotent. For each registered storage, drive MUST call `storage.connect?.()` ONLY when `storage.isConnected?.() !== true`, and MUST record those storages in an internal `connectedByMe: WeakSet<DriveStorage>`. Connection failures MUST surface as `DriveError(DRIVE.STORAGE_CONNECT_FAILED, { cause })`.
|
|
|
|
**Verified by:** `src/drive/drive.spec-conformance.test.ts` (`DRIVE-02`).
|
|
|
|
### DRIVE-03 — `dispose()` is idempotent and ownership-respecting
|
|
|
|
`Drive.dispose()` MUST be idempotent. Drive MUST only close storages in `connectedByMe`; storages pre-connected by the caller MUST be left open. After `dispose()`, the drive transitions to a terminal disposed state.
|
|
|
|
**Verified by:** `src/drive/drive.spec-conformance.test.ts` (`DRIVE-03`).
|
|
|
|
### DRIVE-04 — Operations after `dispose()` throw
|
|
|
|
Any file operation invoked on a disposed drive (`read`, `write`, `delete`, `stat`, `list`, `createReadStream`, `createWriteStream`) MUST throw `DriveError(DRIVE.DISPOSED)`. Operations invoked before `initialize()` MUST throw `DriveError(DRIVE.NOT_INITIALIZED)`.
|
|
|
|
**Verified by:** `src/drive/drive.spec-conformance.test.ts` (`DRIVE-04`).
|
|
|
|
### DRIVE-05 — Error-code registry is namespaced and frozen
|
|
|
|
`DRIVE_CODES` MUST be declared via `defineCodes("DRIVE", [...])` from `@suaveplan/error`. `Object.isFrozen(DRIVE_CODES)` MUST be `true`. Every code value MUST start with `DRIVE.`. `DriveError` MUST extend `SuaveplanError<DriveErrorCode>`.
|
|
|
|
**Verified by:** `src/error-codes.spec-conformance.test.ts` (`DRIVE-05`).
|
|
|
|
### DRIVE-06 — Plugin middleware order
|
|
|
|
`drive.use(plugin)` and `drive.useMiddleware(mw)` MUST install in registration order. Middleware chains for `read`, `write`, `delete`, `stat`, `list` MUST execute outer-first on the request path and outer-last on the response path. `plugin.dispose()` MUST be called in reverse-registration order on `Drive.dispose()`. Plugin install/dispose throws MUST surface as `DriveError(DRIVE.PLUGIN_FAILED, { cause })`.
|
|
|
|
**Verified by:** `src/plugins/registry.spec-conformance.test.ts` (`DRIVE-06`).
|
|
|
|
### DRIVE-07 — Capability fallbacks for streams
|
|
|
|
`drive.createReadStream(path)` MUST use `storage.createReadStream` when `storage.capabilities?.nativeStreams === true`, otherwise MUST fall back to the inherited `AbstractStorage.defaultCreateReadStream`. Same rule for `createWriteStream`.
|
|
|
|
**Verified by:** `src/file-operations/streams.spec-conformance.test.ts` (`DRIVE-07`).
|
|
|
|
### DRIVE-08 — Generic storage typing
|
|
|
|
`Drive<TStorageMap>` MUST narrow `TStorageMap` through `drive.use<K, S>(id, storage)` so that `drive.getStorage(id)` returns `TStorageMap[K]` exactly (no widening to the base `DriveStorage`). Calls with an unknown id MUST be a TypeScript error.
|
|
|
|
**Verified by:** `src/drive/drive.spec-conformance.test.ts` (`DRIVE-08`, type-level via `expectTypeOf`).
|
|
|
|
### DRIVE-09 — Constructor overloads
|
|
|
|
`new Drive()`, `new Drive(storage)`, `new Drive(storage, options)`, and `new Drive({ defaultStorage, plugins, ... })` MUST all be valid. The bare-storage form MUST be observably equivalent to passing `{ defaultStorage: storage }` and MUST register the storage under id `"default"`.
|
|
|
|
**Verified by:** `src/drive/drive.spec-conformance.test.ts` (`DRIVE-09`).
|