@xemahq/storage-driver

Workspace storage adapters, one per backing, with their real semantics

Overview

Every adapter that provisions a workspace storage pool, behind one StorageDriver interface: Kubernetes CSI ReadWriteMany volumes (Longhorn, NFS, AWS EFS, GCP Filestore, Azure Files), a Docker named volume, a Docker Swarm cluster volume, and a host directory for local development. Each adapter is its own subpath, so a deployment loads only what it composes.

The interface is deliberately uniform and the backings are not, so the package also publishes what each one actually does — whether a capacity request is a quota, whether two nodes can hold a pool at once, who creates the per-allocation directory, and how the bytes are reclaimed. A conformance suite ships alongside it and holds every adapter to those declared semantics, so a driver cannot quietly normalise its backing away.

When to use it

• Compose a driver in a service that owns storage pools, choosing the subpath that matches the backing the deployment runs on.
• Read a backing's declared semantics before assuming a capacity number is a limit or that a directory exists once ensureSubPath resolves.
• Run the conformance suite against your own StorageDriver implementation when you add a backing this package does not ship.
• Reach for @xemahq/blob-storage instead for object storage — key/value blobs are a different plane, not a filesystem, and the two must not grow toward each other.

Installation

pnpm add @xemahq/storage-driver

Usage

import { storageBackendProfileFor } from '@xemahq/storage-driver';
import { createK8sCsiStorageDriver } from '@xemahq/storage-driver/k8s-csi';
import { StorageDriverKind } from '@xemahq/kernel-contracts/workspace-storage';

const driver = createK8sCsiStorageDriver({ kind: StorageDriverKind.EFS, k8s });

const pool = await driver.ensurePool({
  slug: 'workspaces-eu',
  driverKind: StorageDriverKind.EFS,
  driverConfig: {},
  capacityBytes: 100n * 1024n ** 3n,
  region: 'eu-west-1',
});

// Whether that number is a quota depends on the backing — ask, do not assume.
storageBackendProfileFor(StorageDriverKind.EFS).capacity.policy; // 'not-enforced'

Peer requirements

• @xemahq/kernel-contracts >=34.3.0 — owns the StorageDriver interface, StorageDriverKind, and the pool/allocation types every adapter speaks.

License

Apache-2.0 © Xema — xema.dev