Filesystem Storage

Alpha

DSAR is currently in alpha. APIs, package surfaces, configuration, and documentation may change as the project evolves.

@dsar/storage-filesystem stores DSAR fulfilment artifacts on the local filesystem. Ideal for development, testing, and single-server deployments.

Installation

Package manager	Command
npm	`npm install @dsar/storage-filesystem`
pnpm	`pnpm add @dsar/storage-filesystem`
yarn	`yarn add @dsar/storage-filesystem`
bun	`bun add @dsar/storage-filesystem`

Setup

import { dsarInstance } from "@dsar/backend";
import { makeFilesystemStorageAdapter } from "@dsar/storage-filesystem";

const runtime = dsarInstance({
	adapters: {
		inbound: "stub",
		notifications: "stub",
		storage: makeFilesystemStorageAdapter({
			baseDir: "./.dsar-artifacts",
			prefix: "artifacts",
			retryMaxAttempts: 1,
		}),
	},
});

Configuration

Option	Default	Description
`baseDir`	—	Local directory for artifacts and sidecar metadata (required)
`prefix`	`artifacts`	Key prefix used by the deterministic key builder
`retryMaxAttempts`	`1`	Retries for retriable filesystem failures

Key Layout

Default deterministic key format:

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

Fallback values:

missing requestId → request-unknown
missing manifestId → manifest-unknown
missing category → uncategorized
missing name/id → artifact.bin

Error and Retry Behaviour

Category	Retriable	Examples
`timeout`	yes	operation timeout (`ETIMEDOUT`)
`network`	yes	temporary resource pressure (`EAGAIN`, `EBUSY`)
`validation`	no	invalid key/path traversal, missing object
`config`	no	base directory permission/configuration issues
`unknown`	no	unmatched filesystem errors

Manifest Linkage

Manifest metadata is stored in sidecar JSON files alongside artifacts so linkage survives process restarts. Each artifact reference preserves:

requestId
manifestId
manifestHash
manifestSignature