Skip to content

armgit / BYOC

Public Imported from GitHub
0

One storage API for Google Drive, Nextcloud, and S3-compatible clouds, in TypeScript and Python.

2.4 KB
Raw Blame

@byoc/local

Local filesystem provider adapter for BYOC (Bring Your Own Cloud).

Part of the BYOC monorepo. Requires @byoc/core.

Status: v0.3.0. Unit tested and certified against the provider compliance suite.

The provider that needs no account, no network, and no credentials. Use it to evaluate BYOC before signing up for anything, to develop offline, and to back a self-hosted deployment with a mounted volume as first-class storage rather than a special case.

Install

npm install @byoc/core @byoc/local

Usage

import { BYOC } from "@byoc/core";
import { LocalFileSystemProvider } from "@byoc/local";

const storage = new BYOC({
  provider: new LocalFileSystemProvider({ rootDirectory: "./storage" })
});

await storage.connect();

await storage.writeText("reports/q3.md", "# Q3");
console.log(await storage.readText("reports/q3.md"));
console.log(await storage.list("reports"));

Swap in S3CompatibleProvider, WebDAVProvider, or GoogleDriveProvider later and none of the calling code changes.

Configuration

Option Type Default Meaning
rootDirectory string required Directory that backs this provider
createRoot boolean true Set false to require the directory to already exist

Capabilities

Capability Supported Notes
folders yes Real directories
serverSideCopy yes fs.cp / fs.rename, no bytes through your process
quota yes Reports the backing filesystem, not the directory
publicUrls no A local path is not reachable by a browser
sharing no
resumableUploads no
versioning no

Path safety

Every path is confined to rootDirectory. .. segments are rejected before they reach the adapter, and the resolved target is rechecked against the resolved root afterwards, so a symlink pointing outside the root cannot be read or written through — a case traversal filtering alone does not catch.

Custom metadata

The filesystem cannot store a MIME type or arbitrary key-value metadata on a file. When you supply either, the adapter writes a sidecar under a single .byoc/ directory at the root. That directory is hidden from list(), so it never appears as content.

If you never pass metadata, no sidecar is written and the directory holds nothing but your own files.

License

Apache-2.0