Skip to content

storage-service.mdx

Latest commit

 

History

History
44 lines (34 loc) · 2.23 KB

storage-service.mdx

File metadata and controls

44 lines (34 loc) · 2.23 KB
Raw
title services.storage
description File/object storage contract for upload/download and presigned URL workflows.

services.storage

  • Stability: stable
  • Canonical source: packages/spec/src/contracts/storage-service.ts

Core Methods

services.storage.upload(key: string, data: Buffer | ReadableStream, options?: StorageUploadOptions): Promise<void>
services.storage.download(key: string): Promise<Buffer>
services.storage.delete(key: string): Promise<void>
services.storage.exists(key: string): Promise<boolean>
services.storage.getInfo(key: string): Promise<StorageFileInfo>
services.storage.list?(prefix: string): Promise<StorageFileInfo[]>
services.storage.getSignedUrl?(key: string, expiresIn: number, options?: PresignedDownloadOptions): Promise<string>

Presigned / Chunked (optional)

services.storage.getPresignedUpload?(key: string, expiresIn: number, options?: StorageUploadOptions): Promise<PresignedUploadDescriptor>
services.storage.getPresignedDownload?(key: string, expiresIn: number, options?: PresignedDownloadOptions): Promise<PresignedDownloadDescriptor>
services.storage.initiateChunkedUpload?(key: string, options?: StorageUploadOptions): Promise<string>
services.storage.uploadChunk?(uploadId: string, partNumber: number, data: Buffer): Promise<string>
services.storage.completeChunkedUpload?(uploadId: string, parts: Array<{ partNumber: number; eTag: string }>): Promise<string>
services.storage.abortChunkedUpload?(uploadId: string): Promise<void>

Typical Errors

Storage methods reject with a plain Error carrying a descriptive message — the built-in adapters do not attach a stable error code. Common cases include:

  • File not found on download / getInfo — the local adapter surfaces the underlying filesystem ENOENT error; reference/mock adapters reject with a File not found: <key> message.
  • Invalid or expired upload session on the chunked methods (e.g. Upload session "<id>" not found).
  • Path-traversal / invalid key rejection from the local adapter (e.g. path traversal not allowed).

A request that fails an upstream permission check surfaces the framework-wide PERMISSION_DENIED error from the security layer (code: 'PERMISSION_DENIED'), not the storage adapter.