@fgv/ts-http-storage 5.1.0-1

package/src/packlets/storage/model.ts

@@ -0,0 +1,113 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type { Result } from '@fgv/ts-utils';
+
+/**
+ * Namespace identifier for scoped storage.
+ * @public
+ */
+export type StorageNamespace = string;
+
+/**
+ * Storage item type.
+ * @public
+ */
+export type StorageItemType = 'file' | 'directory';
+
+/**
+ * Storage tree item metadata.
+ * @public
+ */
+export interface IStorageTreeItem {
+  readonly path: string;
+  readonly name: string;
+  readonly type: StorageItemType;
+}
+
+/**
+ * Response for listing children.
+ * @public
+ */
+export interface IStorageTreeChildrenResponse {
+  readonly path: string;
+  readonly children: ReadonlyArray<IStorageTreeItem>;
+}
+
+/**
+ * Response for reading a file.
+ * @public
+ */
+export interface IStorageFileResponse {
+  readonly path: string;
+  readonly contents: string;
+  readonly contentType?: string;
+}
+
+/**
+ * Request for path-based operations.
+ * @public
+ */
+export interface IStoragePathRequest {
+  readonly path: string;
+  readonly namespace?: StorageNamespace;
+}
+
+/**
+ * Request for writing file contents.
+ * @public
+ */
+export interface IStorageWriteFileRequest extends IStoragePathRequest {
+  readonly contents: string;
+  readonly contentType?: string;
+}
+
+/**
+ * Request for sync operation.
+ * @public
+ */
+export interface IStorageSyncRequest {
+  readonly namespace?: StorageNamespace;
+}
+
+/**
+ * Sync response metadata.
+ * @public
+ */
+export interface IStorageSyncResponse {
+  readonly synced: number;
+}
+
+/**
+ * Provider contract for storage backends.
+ * All methods are async to support both filesystem and database backends.
+ * @public
+ */
+export interface IHttpStorageProvider {
+  getItem(path: string): Promise<Result<IStorageTreeItem>>;
+  getChildren(path: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>>;
+  getFile(path: string): Promise<Result<IStorageFileResponse>>;
+  saveFile(path: string, contents: string, contentType?: string): Promise<Result<IStorageFileResponse>>;
+  deleteFile(path: string): Promise<Result<boolean>>;
+  createDirectory(path: string): Promise<Result<IStorageTreeItem>>;
+  sync(): Promise<Result<IStorageSyncResponse>>;
+}

package/src/packlets/storage/provider.ts

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type { Result } from '@fgv/ts-utils';
+
+import type { IHttpStorageProvider, StorageNamespace } from './model';
+
+/**
+ * Factory for creating namespace-scoped storage providers.
+ * @public
+ */
+export interface IHttpStorageProviderFactory {
+  forNamespace(namespace?: StorageNamespace): Result<IHttpStorageProvider>;
+}

package/src/packlets/storage/routes.ts

@@ -0,0 +1,215 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Hono } from 'hono';
+
+import type { Logging } from '@fgv/ts-utils';
+
+import {
+  storagePathRequest,
+  storageSyncRequest,
+  storageWriteFileRequest,
+  storageTreeChildrenResponse,
+  storageTreeItem,
+  storageFileResponse
+} from './converters';
+import { HttpStorageService } from './service';
+import type { IStoragePathRequest, IStorageSyncRequest } from './model';
+import type { IHttpStorageProviderFactory } from './provider';
+
+/**
+ * Options for creating storage routes.
+ * @public
+ */
+export interface ICreateStorageRoutesOptions {
+  readonly providers: IHttpStorageProviderFactory;
+  readonly logger?: Logging.ILogger;
+}
+
+function parsePathQuery(path: string | undefined, namespace: string | undefined): IStoragePathRequest {
+  return {
+    path: path ?? '/',
+    namespace
+  };
+}
+
+function parseSyncRequest(namespace: string | undefined): IStorageSyncRequest {
+  return { namespace };
+}
+
+/**
+ * Builds storage routes for a Hono app.
+ * @public
+ */
+export function createStorageRoutes(options: ICreateStorageRoutesOptions): Hono {
+  const routes = new Hono();
+  const service = new HttpStorageService(options.providers);
+
+  routes.get('/health', async (c) => {
+    const namespace = c.req.query('namespace');
+    const syncResult = await service.sync(parseSyncRequest(namespace));
+    if (syncResult.isFailure()) {
+      return c.json({ error: syncResult.message }, 500);
+    }
+    return c.json({ status: 'ok', namespace: namespace ?? 'default' });
+  });
+
+  routes.get('/tree/item', async (c) => {
+    const parsed = storagePathRequest.convert(parsePathQuery(c.req.query('path'), c.req.query('namespace')));
+    if (parsed.isFailure()) {
+      return c.json({ error: `invalid request: ${parsed.message}` }, 400);
+    }
+
+    const result = await service.getItem(parsed.value);
+    if (result.isFailure()) {
+      return c.json({ error: result.message }, 404);
+    }
+
+    const converted = storageTreeItem.convert(result.value);
+    if (converted.isFailure()) {
+      return c.json({ error: `invalid response: ${converted.message}` }, 500);
+    }
+    return c.json(converted.value);
+  });
+
+  routes.get('/tree/children', async (c) => {
+    const parsed = storagePathRequest.convert(parsePathQuery(c.req.query('path'), c.req.query('namespace')));
+    if (parsed.isFailure()) {
+      return c.json({ error: `invalid request: ${parsed.message}` }, 400);
+    }
+
+    const result = await service.getChildren(parsed.value);
+    if (result.isFailure()) {
+      return c.json({ error: result.message }, 404);
+    }
+
+    const converted = storageTreeChildrenResponse.convert(result.value);
+    if (converted.isFailure()) {
+      return c.json({ error: `invalid response: ${converted.message}` }, 500);
+    }
+    return c.json(converted.value);
+  });
+
+  routes.get('/file', async (c) => {
+    const parsed = storagePathRequest.convert(parsePathQuery(c.req.query('path'), c.req.query('namespace')));
+    if (parsed.isFailure()) {
+      return c.json({ error: `invalid request: ${parsed.message}` }, 400);
+    }
+
+    const result = await service.getFile(parsed.value);
+    if (result.isFailure()) {
+      return c.json({ error: result.message }, 404);
+    }
+
+    const converted = storageFileResponse.convert(result.value);
+    if (converted.isFailure()) {
+      return c.json({ error: `invalid response: ${converted.message}` }, 500);
+    }
+    return c.json(converted.value);
+  });
+
+  routes.put('/file', async (c) => {
+    const raw = await c.req.json().catch(() => undefined);
+    if (raw === undefined) {
+      return c.json({ error: 'invalid JSON body' }, 400);
+    }
+
+    const parsed = storageWriteFileRequest.convert(raw);
+    if (parsed.isFailure()) {
+      return c.json({ error: `invalid request: ${parsed.message}` }, 400);
+    }
+
+    const result = await service.saveFile(parsed.value);
+    if (result.isFailure()) {
+      return c.json({ error: result.message }, 400);
+    }
+
+    const converted = storageFileResponse.convert(result.value);
+    if (converted.isFailure()) {
+      return c.json({ error: `invalid response: ${converted.message}` }, 500);
+    }
+
+    options.logger?.detail(`storage write: ${parsed.value.namespace ?? 'default'}:${parsed.value.path}`);
+    return c.json(converted.value);
+  });
+
+  routes.delete('/file', async (c) => {
+    const parsed = storagePathRequest.convert(parsePathQuery(c.req.query('path'), c.req.query('namespace')));
+    if (parsed.isFailure()) {
+      return c.json({ error: `invalid request: ${parsed.message}` }, 400);
+    }
+
+    const result = await service.deleteFile(parsed.value);
+    if (result.isFailure()) {
+      return c.json({ error: result.message }, 404);
+    }
+
+    options.logger?.detail(`storage delete: ${parsed.value.namespace ?? 'default'}:${parsed.value.path}`);
+    return c.json({ deleted: result.value });
+  });
+
+  routes.post('/directories', async (c) => {
+    const raw = await c.req.json().catch(() => undefined);
+    if (raw === undefined) {
+      return c.json({ error: 'invalid JSON body' }, 400);
+    }
+
+    const parsed = storagePathRequest.convert(raw);
+    if (parsed.isFailure()) {
+      return c.json({ error: `invalid request: ${parsed.message}` }, 400);
+    }
+
+    const result = await service.createDirectory(parsed.value);
+    if (result.isFailure()) {
+      return c.json({ error: result.message }, 400);
+    }
+
+    const converted = storageTreeItem.convert(result.value);
+    if (converted.isFailure()) {
+      return c.json({ error: `invalid response: ${converted.message}` }, 500);
+    }
+    return c.json(converted.value);
+  });
+
+  routes.post('/sync', async (c) => {
+    const raw = await c.req.json().catch(() => ({}));
+    const parsed = storageSyncRequest.convert(raw);
+    if (parsed.isFailure()) {
+      return c.json({ error: `invalid request: ${parsed.message}` }, 400);
+    }
+
+    const result = await service.sync(parsed.value);
+    if (result.isFailure()) {
+      return c.json({ error: result.message }, 500);
+    }
+
+    return c.json(result.value);
+  });
+
+  routes.onError((err, c) => {
+    const message = err instanceof Error ? err.message : String(err);
+    options.logger?.error(`storage route error: ${message}`);
+    return c.json({ error: message }, 500);
+  });
+
+  return routes;
+}

package/src/packlets/storage/service.ts

@@ -0,0 +1,114 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { fail, type Result, succeed } from '@fgv/ts-utils';
+
+import type {
+  IHttpStorageProvider,
+  IStorageFileResponse,
+  IStoragePathRequest,
+  IStorageSyncRequest,
+  IStorageSyncResponse,
+  IStorageTreeChildrenResponse,
+  IStorageTreeItem,
+  IStorageWriteFileRequest
+} from './model';
+import type { IHttpStorageProviderFactory } from './provider';
+
+/**
+ * Service layer for storage API operations.
+ * @public
+ */
+export class HttpStorageService {
+  private readonly _providers: IHttpStorageProviderFactory;
+
+  public constructor(providers: IHttpStorageProviderFactory) {
+    this._providers = providers;
+  }
+
+  public async getItem(request: IStoragePathRequest): Promise<Result<IStorageTreeItem>> {
+    const providerResult = this._getProvider(request.namespace);
+    if (providerResult.isFailure()) {
+      return fail(providerResult.message);
+    }
+    return providerResult.value.getItem(request.path);
+  }
+
+  public async getChildren(request: IStoragePathRequest): Promise<Result<IStorageTreeChildrenResponse>> {
+    const providerResult = this._getProvider(request.namespace);
+    if (providerResult.isFailure()) {
+      return fail(providerResult.message);
+    }
+    const childrenResult = await providerResult.value.getChildren(request.path);
+    if (childrenResult.isFailure()) {
+      return fail(childrenResult.message);
+    }
+    return succeed({
+      path: request.path,
+      children: childrenResult.value
+    });
+  }
+
+  public async getFile(request: IStoragePathRequest): Promise<Result<IStorageFileResponse>> {
+    const providerResult = this._getProvider(request.namespace);
+    if (providerResult.isFailure()) {
+      return fail(providerResult.message);
+    }
+    return providerResult.value.getFile(request.path);
+  }
+
+  public async saveFile(request: IStorageWriteFileRequest): Promise<Result<IStorageFileResponse>> {
+    const providerResult = this._getProvider(request.namespace);
+    if (providerResult.isFailure()) {
+      return fail(providerResult.message);
+    }
+    return providerResult.value.saveFile(request.path, request.contents, request.contentType);
+  }
+
+  public async deleteFile(request: IStoragePathRequest): Promise<Result<boolean>> {
+    const providerResult = this._getProvider(request.namespace);
+    if (providerResult.isFailure()) {
+      return fail(providerResult.message);
+    }
+    return providerResult.value.deleteFile(request.path);
+  }
+
+  public async createDirectory(request: IStoragePathRequest): Promise<Result<IStorageTreeItem>> {
+    const providerResult = this._getProvider(request.namespace);
+    if (providerResult.isFailure()) {
+      return fail(providerResult.message);
+    }
+    return providerResult.value.createDirectory(request.path);
+  }
+
+  public async sync(request: IStorageSyncRequest): Promise<Result<IStorageSyncResponse>> {
+    const providerResult = this._getProvider(request.namespace);
+    if (providerResult.isFailure()) {
+      return fail(providerResult.message);
+    }
+    return providerResult.value.sync();
+  }
+
+  private _getProvider(namespace?: string): Result<IHttpStorageProvider> {
+    return this._providers.forNamespace(namespace).withErrorFormat((msg) => `provider: ${msg}`);
+  }
+}

package/src/test/unit/storage/fsProvider.test.ts

@@ -0,0 +1,129 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { FsStorageProvider, FsStorageProviderFactory, sanitizeNamespace } from '../../../packlets/storage';
+
+describe('sanitizeNamespace', () => {
+  test('returns default when namespace is empty', () => {
+    expect(sanitizeNamespace(undefined).isSuccess()).toBe(true);
+    expect(sanitizeNamespace('   ').isSuccess()).toBe(true);
+    expect(sanitizeNamespace('   ').orThrow()).toBe('default');
+  });
+
+  test('accepts valid namespace values', () => {
+    const result = sanitizeNamespace('team.alpha_01-dev');
+    expect(result.isSuccess()).toBe(true);
+    expect(result.orThrow()).toBe('team.alpha_01-dev');
+  });
+
+  test('rejects invalid namespace characters', () => {
+    const result = sanitizeNamespace('../escape');
+    expect(result.isFailure()).toBe(true);
+    expect(result.message).toContain('only [a-zA-Z0-9._-] allowed');
+  });
+});
+
+describe('FsStorageProvider', () => {
+  let rootPath: string;
+
+  beforeEach(() => {
+    rootPath = fs.mkdtempSync(path.join(os.tmpdir(), 'ts-http-storage-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(rootPath, { recursive: true, force: true });
+  });
+
+  test('saves and loads files', async () => {
+    const provider = new FsStorageProvider(rootPath);
+
+    const saveResult = await provider.saveFile('/data/example.txt', 'hello');
+    expect(saveResult.isSuccess()).toBe(true);
+
+    const fileResult = await provider.getFile('/data/example.txt');
+    expect(fileResult.isSuccess()).toBe(true);
+    expect(fileResult.orThrow()).toEqual({
+      path: '/data/example.txt',
+      contents: 'hello'
+    });
+  });
+
+  test('lists children in a directory', async () => {
+    const provider = new FsStorageProvider(rootPath);
+    await provider.saveFile('/data/one.txt', 'one');
+    await provider.saveFile('/data/two.txt', 'two');
+
+    const childrenResult = await provider.getChildren('/data');
+    expect(childrenResult.isSuccess()).toBe(true);
+
+    const childNames = childrenResult
+      .orThrow()
+      .map((child) => child.name)
+      .sort();
+    expect(childNames).toEqual(['one.txt', 'two.txt']);
+  });
+
+  test('normalizes traversal-like request paths under storage root', async () => {
+    const provider = new FsStorageProvider(rootPath);
+
+    const result = await provider.getItem('../../etc/passwd');
+    expect(result.isFailure()).toBe(true);
+    expect(result.message).toContain('ENOENT');
+    expect(result.message).toContain(path.join(rootPath, 'etc/passwd'));
+  });
+
+  test('deletes an existing file', async () => {
+    const provider = new FsStorageProvider(rootPath);
+    await provider.saveFile('/data/delete-me.txt', 'temporary');
+
+    const deleteResult = await provider.deleteFile('/data/delete-me.txt');
+    expect(deleteResult.isSuccess()).toBe(true);
+    expect(deleteResult.orThrow()).toBe(true);
+
+    const readResult = await provider.getFile('/data/delete-me.txt');
+    expect(readResult.isFailure()).toBe(true);
+  });
+});
+
+describe('FsStorageProviderFactory', () => {
+  let rootPath: string;
+
+  beforeEach(() => {
+    rootPath = fs.mkdtempSync(path.join(os.tmpdir(), 'ts-http-storage-factory-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(rootPath, { recursive: true, force: true });
+  });
+
+  test('creates namespace-scoped providers', async () => {
+    const factory = new FsStorageProviderFactory({ rootPath });
+
+    const providerResult = factory.forNamespace('team-a');
+    expect(providerResult.isSuccess()).toBe(true);
+
+    const provider = providerResult.orThrow();
+    const saveResult = await provider.saveFile('/notes.txt', 'namespaced');
+    expect(saveResult.isSuccess()).toBe(true);
+
+    const expectedPath = path.join(rootPath, 'team-a', 'notes.txt');
+    expect(fs.existsSync(expectedPath)).toBe(true);
+  });
+
+  test('fails for invalid namespace', () => {
+    const factory = new FsStorageProviderFactory({ rootPath });
+    const result = factory.forNamespace('bad/name');
+
+    expect(result.isFailure()).toBe(true);
+    expect(result.message).toContain('only [a-zA-Z0-9._-] allowed');
+  });
+
+  test('rejects namespace that resolves outside root', () => {
+    const factory = new FsStorageProviderFactory({ rootPath });
+    const result = factory.forNamespace('..');
+
+    expect(result.isFailure()).toBe(true);
+    expect(result.message).toContain('outside root');
+  });
+});