@fgv/ts-http-storage 5.1.0-19 → 5.1.0-20

package/src/packlets/storage/provider.ts

@@ -1,33 +0,0 @@
-/*
- * 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

@@ -1,215 +0,0 @@
-/*
- * 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

@@ -1,114 +0,0 @@
-/*
- * 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

@@ -1,129 +0,0 @@
-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');
-  });
-});

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

@@ -1,165 +0,0 @@
-import { fail, type Result, succeed } from '@fgv/ts-utils';
-
-import {
-  createStorageRoutes,
-  type IHttpStorageProvider,
-  type IHttpStorageProviderFactory,
-  type IStorageFileResponse,
-  type IStorageSyncResponse,
-  type IStorageTreeItem
-} from '../../../packlets/storage';
-
-class InMemoryProvider implements IHttpStorageProvider {
-  private readonly _files: Map<string, string> = new Map();
-
-  private _basename(path: string): string {
-    const parts = path.split('/');
-    return parts[parts.length - 1] ?? '';
-  }
-
-  public async getItem(path: string): Promise<Result<IStorageTreeItem>> {
-    if (this._files.has(path)) {
-      return succeed({ path, name: this._basename(path), type: 'file' as const });
-    }
-    return fail(`${path}: not found`);
-  }
-
-  public async getChildren(path: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>> {
-    const children: IStorageTreeItem[] = [];
-    for (const filePath of this._files.keys()) {
-      if (filePath.startsWith(`${path}/`)) {
-        const name = filePath.substring(path.length + 1);
-        if (!name.includes('/')) {
-          children.push({ path: filePath, name, type: 'file' });
-        }
-      }
-    }
-    return succeed(children);
-  }
-
-  public async getFile(path: string): Promise<Result<IStorageFileResponse>> {
-    const contents = this._files.get(path);
-    if (contents === undefined) {
-      return fail(`${path}: not found`);
-    }
-    return succeed({ path, contents });
-  }
-
-  public async saveFile(path: string, contents: string): Promise<Result<IStorageFileResponse>> {
-    this._files.set(path, contents);
-    return succeed({ path, contents });
-  }
-
-  public async deleteFile(path: string): Promise<Result<boolean>> {
-    if (!this._files.has(path)) {
-      return fail(`${path}: not found`);
-    }
-    this._files.delete(path);
-    return succeed(true);
-  }
-
-  public async createDirectory(path: string): Promise<Result<IStorageTreeItem>> {
-    return succeed({ path, name: this._basename(path), type: 'directory' });
-  }
-
-  public async sync(): Promise<Result<IStorageSyncResponse>> {
-    return succeed({ synced: this._files.size });
-  }
-}
-
-class TestProviderFactory implements IHttpStorageProviderFactory {
-  private readonly _provider: InMemoryProvider;
-
-  public constructor(provider: InMemoryProvider) {
-    this._provider = provider;
-  }
-
-  public forNamespace(): Result<IHttpStorageProvider> {
-    return succeed(this._provider);
-  }
-}
-
-describe('createStorageRoutes', () => {
-  test('writes then reads a file', async () => {
-    const provider = new InMemoryProvider();
-    const app = createStorageRoutes({ providers: new TestProviderFactory(provider) });
-
-    const putResponse = await app.request(
-      new Request('http://localhost/file', {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ path: '/data/demo.txt', contents: 'hello' })
-      })
-    );
-    expect(putResponse.status).toBe(200);
-
-    const getResponse = await app.request(new Request('http://localhost/file?path=/data/demo.txt'));
-    expect(getResponse.status).toBe(200);
-    await expect(getResponse.json()).resolves.toEqual({ path: '/data/demo.txt', contents: 'hello' });
-  });
-
-  test('returns 400 for invalid put body', async () => {
-    const provider = new InMemoryProvider();
-    const app = createStorageRoutes({ providers: new TestProviderFactory(provider) });
-
-    const response = await app.request(
-      new Request('http://localhost/file', {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: '{ not-json'
-      })
-    );
-
-    expect(response.status).toBe(400);
-    const payload = (await response.json()) as { error?: string };
-    expect(payload.error).toContain('invalid JSON body');
-  });
-
-  test('returns sync payload from provider', async () => {
-    const provider = new InMemoryProvider();
-    const app = createStorageRoutes({ providers: new TestProviderFactory(provider) });
-
-    await app.request(
-      new Request('http://localhost/file', {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ path: '/alpha.txt', contents: 'a' })
-      })
-    );
-
-    const response = await app.request(
-      new Request('http://localhost/sync', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({})
-      })
-    );
-
-    expect(response.status).toBe(200);
-    await expect(response.json()).resolves.toEqual({ synced: 1 });
-  });
-
-  test('deletes a file through DELETE /file', async () => {
-    const provider = new InMemoryProvider();
-    const app = createStorageRoutes({ providers: new TestProviderFactory(provider) });
-
-    await app.request(
-      new Request('http://localhost/file', {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ path: '/data/remove-me.txt', contents: 'gone soon' })
-      })
-    );
-
-    const deleteResponse = await app.request(
-      new Request('http://localhost/file?path=/data/remove-me.txt', {
-        method: 'DELETE'
-      })
-    );
-    expect(deleteResponse.status).toBe(200);
-    await expect(deleteResponse.json()).resolves.toEqual({ deleted: true });
-
-    const getResponse = await app.request(new Request('http://localhost/file?path=/data/remove-me.txt'));
-    expect(getResponse.status).toBe(404);
-  });
-});