What it does
File bytes go to a local directory or an S3-compatible bucket; the metadata (name, type, size, SHA-256, backend key) is an entity in the log. A Supabase-style storage API adds buckets, per-bucket policies, public URLs and signed URLs, all scoped to the calling project.
How it works
On upload, the service hashes the bytes, writes them to the configured backend under a key built from the hash prefix, a generated id and a sanitised file name, and then records the metadata entity. Local storage writes the file and syncs it. The S3-compatible backend sends SigV4-signed requests using path-style or virtual-hosted URLs, and is intended for S3-compatible endpoints such as S3, R2 and MinIO. Whole objects are buffered in memory, and the server limits a request body to 64 MiB.
The project-facing API is /storage/v1. POST /storage/v1/bucket creates a bucket, public or private; /storage/v1/object/{bucket}/{path} uploads, downloads and deletes; /storage/v1/object/list/{bucket} lists; /storage/v1/object/info/{bucket}/{path} describes. Access follows a fixed order: a service key passes; otherwise bucket policies, if any, are evaluated with an owner, path and size context, with any granting policy sufficient; with no policies, a public bucket allows reads and requires an authenticated user for writes, and a private bucket requires an authenticated user for everything.
POST /storage/v1/object/sign/{bucket}/{path} returns a signed URL. The token is an HMAC-SHA256 over the project, bucket, path and expiry, under a server secret, so a URL signed for one project does not verify for another. Public buckets are also reachable at /storage/v1/object/public/{project}/{bucket}/{path}. Bucket and object records are stored under project-prefixed kinds and ids.
The /v1/files route is an operator interface, not a client API; clients use /storage/v1.
Backends are chosen with KYNETRA_FILE_BACKEND (local, the default, or s3). The local root defaults to a blobs directory inside the data directory and can be set with KYNETRA_FILE_DIR. The S3 settings are KYNETRA_S3_ENDPOINT, KYNETRA_S3_REGION, KYNETRA_S3_BUCKET, KYNETRA_S3_ACCESS_KEY, KYNETRA_S3_SECRET_KEY and KYNETRA_S3_PATH_STYLE.
Where you reach it
- HTTP
POST, GET /storage/v1/bucket; GET, DELETE /storage/v1/bucket/{name} - HTTP
POST, GET, DELETE /storage/v1/object/{bucket}/{path}; POST /storage/v1/object/sign/{bucket}/{path} - HTTP
GET /storage/v1/object/public/{project}/{bucket}/{path}; GET /storage/v1/object/signed/{project}/{bucket}/{path} - HTTP
POST, GET /v1/files; GET, DELETE /v1/files/{id} (operator credentials) - Config
KYNETRA_FILE_BACKEND=local|s3, KYNETRA_FILE_DIR, KYNETRA_S3_*
Limits
- File bytes are not in the log. Database backups, log rewind and replication carry the metadata but not the file bytes; a restore that asks for file objects is refused rather than silently partial.
- The S3-compatible backend has no test against a live endpoint in the engine repository; its upload path is covered by signing and URL tests and by fakes.
- Uploads are buffered whole in memory and limited to 64 MiB per request. There is no resumable or multipart upload.
- Image transformation parameters are accepted and ignored; objects come back unchanged.
- A failure between writing the object and recording its metadata can leave an unreferenced object in the backend.
Evidence
- On this siteHTTP API reference
- TestsCovered in the engine repository by 4 file-service tests (round trip, newest-first listing, bounded reads) and 16 storage API tests (path sanitising, bucket names, signed-URL round trips and tampering, cross-project token rejection, cross-tenant isolation, object policies)
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to talk through the limits above against your own workload.