import { type AssetStreamOptions, type StreamAssetDescriptor, type StreamAssetInput, type AssetPutOptions, type AssetSigner, type AssetSignOptions, type AssetStat, type AssetStore, type ByteAssetDescriptor, type ByteAssetInput } from './asset-support.js'; /** Options for a store that keeps assets as files on local disk. */ export interface FilesystemAssetStoreOptions { /** Directory the store owns. Created on first write if missing. */ directory: string; /** Largest single asset accepted, in bytes. */ maxAssetBytes?: number; /** * Lifetime for assets stored without their own, in seconds. Without it, assets are kept until * deleted. */ defaultTtlSeconds?: number; /** Creates asset ids. Defaults to random ids. */ createAssetId?: () => string; /** Replaces the system clock, for tests. */ now?: () => Date; /** * Produces URLs for `sign()`, such as a route on your own server. Without one, signing throws. */ signer?: AssetSigner; } /** * Asset persistence on local disk. * * Each asset is two files: the bytes, and a JSON sidecar holding the descriptor, tenant, and * expiry. Metadata is deliberately not kept in one index file — a single index is a write-contention * point and a corruption blast radius, whereas per-asset sidecars let two processes write different * assets concurrently and lose at most one record if a write is interrupted. * * Suitable for a single host or a shared volume. It does not coordinate deletes across processes, * so a purge running in two places may both attempt the same removal; that is idempotent here. */ export declare class FilesystemAssetStore implements AssetStore { private readonly directory; private readonly maxAssetBytes?; private readonly defaultTtlSeconds?; private readonly createAssetId; private readonly clock; private readonly signer?; constructor(options: FilesystemAssetStoreOptions); /** Writes an asset and its metadata to disk. */ put(input: ByteAssetInput, options: AssetPutOptions): Promise; /** * Reads an asset with its bytes, or `undefined` when it does not exist, has expired, or belongs * to another tenant. */ get(assetId: string, tenantId: string): Promise; /** * Writes a streamed asset to disk a chunk at a time, as fast as the disk takes it, never holding * the whole asset. The size limit and checksum are checked as the bytes flow, and an asset that * fails either leaves no file behind. */ putStream(input: StreamAssetInput, options: AssetPutOptions): Promise; /** Reads an asset, or a range of it, from disk as a stream, or `undefined` as `get()` would. */ getStream(assetId: string, tenantId: string, options?: AssetStreamOptions): Promise; /** Describes an asset without reading its bytes. */ stat(assetId: string, tenantId: string): Promise; /** Deletes an asset. Resolves `true` when it existed. */ delete(assetId: string, tenantId: string): Promise; /** Returns a URL from the configured signer. Throws when no signer is configured. */ sign(assetId: string, tenantId: string, options?: AssetSignOptions): Promise; /** Deletes expired assets, returning how many went. */ purgeExpired(): Promise; private ownedRecord; private readRecord; private removeFiles; private assetPath; private recordPath; } /** * The S3 operations the store needs. * * Structural rather than importing the AWS SDK, so this package stays dependency-free and the same * contract covers S3, R2, MinIO, or a test double. */ export interface S3LikeClient { /** Writes an object. */ putObject(input: { bucket: string; key: string; body: Uint8Array; contentType?: string; metadata?: Record; }): Promise; /** Reads an object and its metadata. */ getObject(input: { bucket: string; key: string; }): Promise<{ body: Uint8Array; metadata?: Record; }>; /** Reads an object's metadata without its body. */ headObject?(input: { bucket: string; key: string; }): Promise<{ metadata?: Record; } | undefined>; /** Deletes an object. */ deleteObject(input: { bucket: string; key: string; }): Promise; /** Lists objects under a prefix. */ listObjects(input: { bucket: string; prefix: string; }): Promise>; /** Produces a presigned URL for an object. */ getSignedUrl?(input: { bucket: string; key: string; expiresInSeconds?: number; }): Promise; /** * Writes an object from a stream, as a multipart upload does, for content too large to buffer. * With `@aws-sdk/lib-storage`, an `Upload` over the body. Optional: without it, a streamed asset is * buffered within `maxAssetBytes` and written with `putObject()`. */ putObjectStream?(input: { bucket: string; key: string; body: ReadableStream; contentType?: string; metadata?: Record; }): Promise; /** * Reads an object, or the range of it, both ends inclusive, as a stream. Optional: without it, the * object is read whole with `getObject()`. */ getObjectStream?(input: { bucket: string; key: string; range?: { start: number; end: number; }; }): Promise<{ body: ReadableStream; }>; } /** Options for a store that keeps assets in an S3-compatible bucket. */ export interface S3AssetStoreOptions { /** The S3 client, through the structural interface above, so no AWS SDK becomes a dependency. */ client: S3LikeClient; /** The bucket the store writes to. */ bucket: string; /** Key prefix owned by this store. Defaults to `nexus-assets/`. */ prefix?: string; /** Largest single asset accepted, in bytes. */ maxAssetBytes?: number; /** * Lifetime for assets stored without their own, in seconds. Without it, assets are kept until * deleted. */ defaultTtlSeconds?: number; /** Creates asset ids. Defaults to random ids. */ createAssetId?: () => string; /** Replaces the system clock, for tests. */ now?: () => Date; /** Overrides the client's own signer. */ signer?: AssetSigner; } /** * Asset persistence on any S3-compatible object store. * * Bytes and a JSON sidecar are two objects under the same key prefix, mirroring the filesystem * store, so retention and tenant rules behave identically across both. * * `purgeExpired()` lists and deletes lapsed sidecars, which costs a LIST per call. On a large bucket * prefer the provider's own lifecycle rules and treat this as the fallback for stores that have * none; the method is exact but not cheap, and that trade is deliberate rather than hidden. */ export declare class S3AssetStore implements AssetStore { private readonly options; private readonly prefix; private readonly maxAssetBytes?; private readonly defaultTtlSeconds?; private readonly createAssetId; private readonly clock; private readonly signer?; constructor(options: S3AssetStoreOptions); /** Writes an asset and its metadata to the bucket. */ put(input: ByteAssetInput, options: AssetPutOptions): Promise; /** * Reads an asset with its bytes, or `undefined` when it does not exist, has expired, or belongs * to another tenant. */ get(assetId: string, tenantId: string): Promise; /** * Stores a streamed asset. With a client that has `putObjectStream()`, the bytes flow straight to the * bucket, checked against the size limit and hashed on the way; the object's metadata then carries * the tenant, since the checksum is known only at the end, and the sidecar carries both. Without * one, the stream is read into memory within `maxAssetBytes` (64 MiB when unset) and stored by `put()`. */ putStream(input: StreamAssetInput, options: AssetPutOptions): Promise; /** * Reads an asset, or a range of it, as a stream: straight from the bucket with a client that has * `getObjectStream()`, otherwise from `getObject()`. */ getStream(assetId: string, tenantId: string, options?: AssetStreamOptions): Promise; /** Describes an asset without reading its bytes. */ stat(assetId: string, tenantId: string): Promise; /** Deletes an asset. Resolves `true` when it existed. */ delete(assetId: string, tenantId: string): Promise; /** Returns a presigned URL from the configured signer or the client's own. */ sign(assetId: string, tenantId: string, options?: AssetSignOptions): Promise; /** Deletes expired assets, returning how many went. */ purgeExpired(): Promise; private ownedRecord; private readRecord; private removeObjects; private objectKey; private recordKey; }