Storage Vercel Blob Adapter Integration

This document describes how to register and use @dsar/storage-vercel-blob with backend runtime.

Runtime Registration

import { dsarInstance } from "@dsar/backend";
import { makeVercelBlobStorageAdapter } from "@dsar/storage-vercel-blob";

const runtime = dsarInstance({
	adapters: {
		inbound: "stub",
		notifications: "stub",
		storage: makeVercelBlobStorageAdapter({
			prefix: "artifacts",
			readWriteToken: process.env.BLOB_READ_WRITE_TOKEN,
			retryMaxAttempts: 3,
			timeoutMs: 3000,
		}),
	},
});

Config Fields

• readWriteToken (optional, defaults to process.env.BLOB_READ_WRITE_TOKEN)
• prefix (optional, default artifacts)
• addRandomSuffix (optional, default false)
• allowOverwrite (optional, default false)
• cacheControlMaxAge (optional)
• timeoutMs (optional, default 10000)
• retryMaxAttempts (optional, default 3)

Key Strategy Reference

Default deterministic key layout:

<prefix>/<requestId>/<manifestId>/<category>/<redaction>/<thirdParty>/<artifactName>

Fallback behavior:

• missing requestId => request-unknown
• missing manifestId => manifest-unknown
• missing category => uncategorized
• missing name/id => artifact.bin

Error and Retry Behavior Matrix

Manifest Linkage

Storage operations preserve manifest-linked metadata on artifact references:

• requestId
• manifestId
• manifestHash
• manifestSignature

For providers that do not expose arbitrary object metadata, the adapter keeps in-process reference metadata and falls back to deterministic key parsing for requestId and manifestId.

Caching and Overwrite Notes

• Vercel Blob put(...) requires access: "public" and serves content through CDN cache.
• Prefer immutable pathnames and keep allowOverwrite disabled unless you explicitly need mutation.
• If overwrite is enabled, cached clients may still observe stale content until cache expiry (cacheControlMaxAge).