defuss-backplane 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +3 -0
- package/ARCH.md +66 -0
- package/LICENSE +21 -0
- package/README.md +173 -2
- package/dist/THIRD-PARTY-LICENSES.txt +83 -0
- package/dist/cli.js +7303 -0
- package/dist/client.d.ts +172 -0
- package/dist/client.js +146 -0
- package/dist/config-itdy3nLB.js +42 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +4 -0
- package/package.json +56 -4
package/.env.example
ADDED
package/ARCH.md
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# Architecture
|
|
2
|
+
|
|
3
|
+
The daemon binds a single IPv4 socket to 127.0.0.1. Node.js and Bun run the same ESM build and use the same disk layout. A local application owns its public HTTP API and its end-user access decisions.
|
|
4
|
+
|
|
5
|
+
| Boundary | Responsibility |
|
|
6
|
+
| --- | --- |
|
|
7
|
+
| Server | Validates Host, Origin and the bot credential before dispatch, including schema and tool discovery. Caps `/rpc` and `/mcp` request bodies at 1 MiB. `/vfs/object` streams file bytes in either direction without that cap. |
|
|
8
|
+
| RPC | defuss-rpc registers the cache, database and file functions and returns DSON results. The backend client authenticates its own discovery fetch because defuss-rpc 3.0.0 omits custom headers on that request. |
|
|
9
|
+
| MCP | defuss-mcp publishes named JSON schemas and validates the arguments. The adapter maps named fields into the RPC call order and passes each call to the same in-process dispatcher. A document can have arbitrary fields, so the adapter uses the registry's JSON schema API. |
|
|
10
|
+
| Engines | defuss-dbsonl 0.9.0 stores cache entries. defuss-db 3.1.0 stores documents in named collections. defuss-vfs 0.3.0 stores files in one volume per bucket. Each service module owns one handle pool. |
|
|
11
|
+
|
|
12
|
+
## Request flow
|
|
13
|
+
|
|
14
|
+
Every request passes the server's checks before either protocol parses it, and both protocols end in the same service functions. Each node names the module or package that owns the step.
|
|
15
|
+
|
|
16
|
+
```mermaid
|
|
17
|
+
flowchart LR
|
|
18
|
+
backend["Backend client or curl"] -->|"POST /rpc, GET or PUT /vfs/object"| server["server.ts: Host, Origin, bearer key"]
|
|
19
|
+
agent["MCP client"] -->|"POST /mcp"| server
|
|
20
|
+
server -->|"1 MiB bodies"| rpc["defuss-rpc registry"]
|
|
21
|
+
server -->|"1 MiB bodies"| mcp["tools.ts: defuss-mcp schemas"]
|
|
22
|
+
server -->|"object streams"| vfs["vfs.ts"]
|
|
23
|
+
mcp -->|"named fields as positional arguments"| rpc
|
|
24
|
+
rpc --> cache["cache.ts"]
|
|
25
|
+
rpc --> db["db.ts"]
|
|
26
|
+
rpc --> vfs
|
|
27
|
+
cache --> dbsonl["defuss-dbsonl: one store per cache bucket"]
|
|
28
|
+
db --> ddb["defuss-db: document databases per tenant"]
|
|
29
|
+
vfs --> volume["defuss-vfs: one volume per file bucket"]
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`faults.ts` wraps each dispatch so that a service fault keeps its code and status in both protocols. `scope.ts` validates and encodes the scope, key and ID before `cache.ts`, `db.ts` or `vfs.ts` leases a handle from its own `pool.ts` pool. `storage.ts` holds the filesystem checks that the pools use, and `services.ts` composes the three services for the daemon and the tests. Splitting by engine keeps each revision protocol next to the store whose transaction it relies on. The pure validation stays separate from the filesystem.
|
|
33
|
+
|
|
34
|
+
The file endpoint streams a request body into one defuss-vfs `putStream` call, and a download pipes one `getStream` snapshot into the response. defuss-rpc 3.0.0 also offers upload and download routes, which this daemon keeps closed. VERIFIED from its source: an upload spools the whole body to a temporary file before the handler runs, keeps a session under an upload ID the client chooses, and reports a handler failure inside an HTTP 200 response. Its stock client also sends the resume probe without custom headers, so the bearer check would reject it. The direct stream writes each byte once, holds no session state and returns faults with their HTTP status in the `/rpc` error body.
|
|
35
|
+
|
|
36
|
+
The release bundles code from the pinned defuss-db package and its search libraries. The database opens through its public `openDatabase` API with a native file backend. This keeps its storage format and leaves model runtimes out of the consumer installation.
|
|
37
|
+
|
|
38
|
+
## Storage and concurrency
|
|
39
|
+
|
|
40
|
+
A logical identifier becomes a lowercase hexadecimal representation of its UTF-8 bytes with an alphabetic prefix. This maps distinct identifiers to distinct filesystem components, even on case-insensitive volumes. The app directory contains its tenant directories. Within each tenant, each cache bucket has a KV store, each file bucket has a defuss-vfs volume directory, and DB buckets are named collections. Short names share one database per tenant. When an encoded name exceeds the engine's 64-character collection limit, its remaining digits select a database subdirectory so long names with a common prefix stay distinct. Identical names in different services select different storage.
|
|
41
|
+
|
|
42
|
+
Each engine pool holds up to 32 handles. A lease keeps its handle open until the operation finishes. Cold opens serialize within the pool to coalesce concurrent requests for the same store. On reaching capacity, a cold open evicts the least recently used idle handle. If all handles are busy, the caller receives an error and may retry that operation. A download holds its volume lease until its stream ends, fails or is cancelled. VERIFIED by probe: closing a volume fails the reads of an open `getStream` snapshot, so the lease keeps the pool from evicting it. A client that disconnects mid-download cancels the stream and releases the lease. VERIFIED by probe on both runtimes: a client that stays connected but stops reading keeps its lease for at least 75 seconds, so each stalled reader holds one of the 32 handles until it disconnects or the daemon shuts down.
|
|
43
|
+
|
|
44
|
+
Cache TTL is an absolute expiry on the daemon clock. A read reports an expired entry as a miss. Expired entries stay on disk until overwritten or explicitly deleted. A cold read checks the shard directory under the pool admission queue. Only a confirmed empty or missing directory qualifies as absent. Existing stores open with creation disabled so an I/O failure propagates. Each write uses its engine's commit protocol. Operations across engines commit independently. A streamed upload publishes the object once, after its last chunk, so a failed upload leaves the previous object and revision.
|
|
45
|
+
|
|
46
|
+
## Revisions
|
|
47
|
+
|
|
48
|
+
A file's revision is the content revision that defuss-vfs stores with the object. A conditional write passes the token as `ifMatch`, and a null token as `ifAbsent`, so the comparison and the publication share one volume transaction.
|
|
49
|
+
|
|
50
|
+
A cache write stores a random token with the value. A conditional change reads the entry, compares its logical revision including TTL, and stages its mutation inside one DBSONL transaction. A v0.1 cache entry derives its first token from its address and persisted entry revision.
|
|
51
|
+
|
|
52
|
+
In each database partition the user collection starts with `x` and its companion revision collection starts with `v`. The document and token share a native database transaction. A versioned read uses one snapshot for both collections. A legacy document derives a scoped initial token from its typed primary key and the database identity. Reads need no migration write. Successful inserts and updates assign a fresh token, including updates that restore earlier content. Deletes remove both records. Internal metadata stays out of user documents, projections and application bucket names. Revision guarantees cover writes through this daemon. Older daemons and native writers do not maintain the companion collection.
|
|
53
|
+
|
|
54
|
+
Each network call owns its fault context. The adapters preserve engine error codes before defuss-rpc or defuss-mcp reduces an exception to a message. Successful calls use the protocol's original response. A schema rejection retains its MCP field corrections.
|
|
55
|
+
|
|
56
|
+
## Security and operations
|
|
57
|
+
|
|
58
|
+
The daemon requires a bearer key for every network request. It accepts Host values for 127.0.0.1 or localhost at its configured port and rejects any request carrying Origin. The backend client uses a literal loopback URL and rejects redirects. Local processes sharing a bot key share access to all app shards. A backend derives tenant selection from its own authenticated request. Containers need a common network namespace to use this listener.
|
|
59
|
+
|
|
60
|
+
The service creates data directories with owner-only mode on POSIX. Run it under an account that owns its data root and credentials. Cache entries, documents and files persist on disk unencrypted and may contain personal data supplied by the application. The application operator controls retention and backups. The listener has no total request deadline, so long transfers can finish. On shutdown it stops accepting connections and gives active requests 3 seconds, then closes the remaining connections before the engine pools close. VERIFIED by probe and the packed-consumer test: a client that stops reading a large download keeps its connection open, and the daemon still exits 0 on SIGTERM. Closing the connection aborts an unfinished upload, which keeps the previous object.
|
|
61
|
+
|
|
62
|
+
The packed-consumer test installs the tarball into a temporary application and exercises all fifteen tools. It uses the official MCP client, curl and the typed client. It starts from a fixture written by the v0.1.0 release tarball (SHA-256 fec0fccbbb34e0933578cb9094ddecb994117ccbb4935bf9ff6d1f97928f09d8). Each of six consumer phases upgrades one legacy cache entry and document. Restarts on the same files check revision continuity across runtimes. Concurrent RPC and MCP writes using the same token verify one winning mutation per item. Each phase streams a file larger than 1 MiB through the client and through curl, and the next phase reads the previous phase's file on the other runtime.
|
|
63
|
+
|
|
64
|
+
The consumer scripts are TypeScript files that Node.js type stripping and Bun run without a build step. Before they run, the strict compiler checks them against the packed declarations and rejects syntax that type stripping cannot erase.
|
|
65
|
+
|
|
66
|
+
In each of the three daemon runs, lsof must list `127.0.0.1:<port>` as the daemon's only TCP listener; it lists wildcard IPv4 and IPv6 listeners as `*:<port>`. A connection attempt to 127.0.0.2 cannot make this distinction on the macOS development host: that address is unassigned there, so wildcard and loopback listeners both time out.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Aron Homberg
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,174 @@
|
|
|
1
|
-
#
|
|
1
|
+
# defuss-backplane
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Local, unified low-level persistence and logic layer RPC service for application service backend and MCP agents. One process serves defuss-rpc, MCP and a streaming file endpoint on the same port. Each bucket belongs to one app, tenant and service.
|
|
4
|
+
|
|
5
|
+
## Quick start
|
|
6
|
+
|
|
7
|
+
The source ZIP includes the installable tarball in its `release` directory. Copy the tarball into your application's directory. From that directory, install it with one of these commands.
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install ./defuss-backplane-0.2.0.tgz
|
|
11
|
+
# or
|
|
12
|
+
bun add ./defuss-backplane-0.2.0.tgz
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
The release bundles the defuss-db engine code reached by the daemon. npm or bun installs defuss-vfs, the file engine, as a regular dependency. Installing the tarball avoids the model runtimes in the development dependency tree.
|
|
16
|
+
|
|
17
|
+
In the directory where the daemon will run, create a private bot key once. Skip this command if you already have a configured `.env`.
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
(umask 077; set -C; printf 'API_KEY=%s\n' "$(openssl rand -hex 32)" > .env)
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Start one daemon with Node.js 26 or Bun 1.4.4 or later. The first command runs the installed CLI under Node.js. The second selects Bun explicitly.
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
node node_modules/defuss-backplane/dist/cli.js
|
|
27
|
+
# or
|
|
28
|
+
bun node_modules/defuss-backplane/dist/cli.js
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
The startup log prints the listener address. The default is `http://127.0.0.1:43127`. Give backend processes and local MCP clients the same bot key. Node.js callers can load their environment file with `node --env-file=.env`.
|
|
32
|
+
|
|
33
|
+
## Backend API
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
import { connectBackplane } from "defuss-backplane/client";
|
|
37
|
+
|
|
38
|
+
const shop = await connectBackplane({ app: "shop" });
|
|
39
|
+
const tenant = shop.tenant("acme");
|
|
40
|
+
const cache = tenant.cache("catalog");
|
|
41
|
+
await cache.set("currency", "EUR", 60_000);
|
|
42
|
+
const cached = await cache.get("currency"); // { hit: true, value: "EUR" }
|
|
43
|
+
|
|
44
|
+
const orders = tenant.db("orders");
|
|
45
|
+
const id = await orders.insert({ item: "A7", status: "open" });
|
|
46
|
+
await orders.update(id, { status: "paid" });
|
|
47
|
+
const page = await orders.query({
|
|
48
|
+
filters: [{ field: "status", op: "eq", value: "paid" }],
|
|
49
|
+
sorters: [{ field: "item", direction: "asc" }],
|
|
50
|
+
projection: ["id", "item"],
|
|
51
|
+
limit: 25,
|
|
52
|
+
});
|
|
53
|
+
console.log(cached, page.rows);
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
| Operation | Result |
|
|
57
|
+
| --- | --- |
|
|
58
|
+
| `cache.get(key)` | `{hit:false}` for a missing or expired key, otherwise `{hit:true,value}`. |
|
|
59
|
+
| `cache.getVersioned(key)` | Returns the value and revision, or `{found:false,revision:null}`. |
|
|
60
|
+
| `cache.set(key,value,ttlMsOrOptions?)` | Overwrites the value and returns true. Omitting TTL clears any previous expiry. Zero expires immediately. |
|
|
61
|
+
| `cache.delete(key,options?)` | Returns true after the storage operation, including when the key is absent. |
|
|
62
|
+
| `db.insert(document,options?)` | Returns the primary key. The database generates one when the document omits `id`. |
|
|
63
|
+
| `db.get(id)` | Returns the document or null. |
|
|
64
|
+
| `db.getVersioned(id)` | Returns the document and revision from one snapshot, or `{found:false,revision:null}`. |
|
|
65
|
+
| `db.update(id,patch,options?)` | Patches fields and returns whether a document was updated. The ID is immutable. |
|
|
66
|
+
| `db.delete(id,options?)` | Returns whether a document was deleted. |
|
|
67
|
+
| `db.query(request?)` | Returns `{rows}` with filters, sorters, offset, limit and optional top-level field projection. Default limit 100, maximum 1,000. |
|
|
68
|
+
|
|
69
|
+
The client sends credentials on its initial schema request and subsequent calls. It sends each immutable scope with the operation. RPC accepts DSON values, including dates and binary data.
|
|
70
|
+
|
|
71
|
+
## Conditional writes
|
|
72
|
+
|
|
73
|
+
Read a revision when a backend or agent will edit a value. A hit returns `{found:true,value,revision}`. Pass the token to the write. A competing update or delete returns `REVISION_CONFLICT`. Read again and decide whether the edit still applies.
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
const order = await orders.getVersioned(id);
|
|
77
|
+
if (order.found) {
|
|
78
|
+
await orders.update(id, { status: "shipped" }, { ifRevision: order.revision });
|
|
79
|
+
}
|
|
80
|
+
await cache.set("job-7", { state: "claimed" }, { ttlMs: 30_000, ifRevision: null });
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Omitting `ifRevision` keeps the v0.1 write behavior. A null token requires logical absence, including an expired cache key. An insert accepts null or an omitted condition and always creates a new row. An update of an absent row returns false if its precondition passes. Recreating a deleted item issues a fresh token even for identical contents. A token applies to one item, survives daemon restarts, and remains valid across writes to other items. Route all edits through the daemon when using revisions. Native readers can still open the document store. A typed collection requires an explicit ID when its declared ID type excludes arbitrary strings.
|
|
84
|
+
|
|
85
|
+
## Files
|
|
86
|
+
|
|
87
|
+
`tenant.vfs(bucket)` stores files as objects under relative path keys. Calls through `/rpc` and MCP carry at most 1 MiB. `upload` and `download` stream objects of any size through `/vfs/object`.
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
import { createReadStream, createWriteStream } from "node:fs";
|
|
91
|
+
import { Writable } from "node:stream";
|
|
92
|
+
|
|
93
|
+
const media = tenant.vfs("media");
|
|
94
|
+
await media.put("notes/today.txt", "Call the supplier");
|
|
95
|
+
const listing = await media.list({ prefix: "notes/" });
|
|
96
|
+
|
|
97
|
+
await media.upload("videos/intro.mp4", createReadStream("intro.mp4"), { ifRevision: null });
|
|
98
|
+
const video = await media.download("videos/intro.mp4");
|
|
99
|
+
if (video.found) await video.stream.pipeTo(Writable.toWeb(createWriteStream("copy.mp4")));
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
| Operation | Result |
|
|
103
|
+
| --- | --- |
|
|
104
|
+
| `vfs.put(key,data,options?)` | Stores a string or bytes as one object and returns `{key,size,revision,mtimeMs}`. |
|
|
105
|
+
| `vfs.get(key,range?)` | Returns the bytes with that metadata, or `{found:false,revision:null}`. An object over 1 MiB needs a `{offset,length}` range or `download`. |
|
|
106
|
+
| `vfs.head(key)` | Returns the metadata without the bytes. |
|
|
107
|
+
| `vfs.list(request?)` | Returns `{objects,nextAfter}` in bytewise key order. `prefix`, `after` and `limit` (default 100, maximum 1,000) select a page. Pass `nextAfter` as `after` for the next page. |
|
|
108
|
+
| `vfs.delete(key,options?)` | Returns whether an object was deleted. |
|
|
109
|
+
| `vfs.upload(key,body,options?)` | Streams a `ReadableStream`, an async iterable such as a Node.js file stream, a `Blob`, bytes or a string, and returns the metadata. |
|
|
110
|
+
| `vfs.download(key)` | Returns the metadata with a `stream` of the bytes, or `{found:false,revision:null}`. Read or cancel the stream. |
|
|
111
|
+
|
|
112
|
+
A key is a relative path of 1 to 1,024 valid UTF-8 bytes without empty, `.` or `..` segments. A key cannot hold an object while it is also the directory of other keys: with `a/b` stored, writing `a` fails with `INVALID_ARGUMENT`, and reading `a` finds nothing. Writes take `ifRevision` as described above. Every successful write issues a new revision, even for unchanged content. An upload replaces the previous object only after its last byte arrives, so a failed upload leaves the previous object and revision in place.
|
|
113
|
+
|
|
114
|
+
The streaming endpoint takes the scope and key as URL-encoded query parameters. `PUT` stores the request body and returns the metadata as JSON. `GET` returns the bytes with `Content-Length`, the revision as a quoted `ETag` and the modification time in `X-Mtime-Ms`. A missing object returns 404 with code `NOT_FOUND`. `If-Match: "<revision>"` and `If-None-Match: *` are the HTTP forms of a revision token and of `ifRevision: null`.
|
|
115
|
+
|
|
116
|
+
```sh
|
|
117
|
+
object='http://127.0.0.1:43127/vfs/object?app=shop&tenant=acme&bucket=media&key=videos%2Fintro.mp4'
|
|
118
|
+
curl -fsS -T intro.mp4 -H "Authorization: Bearer ${API_KEY}" "$object"
|
|
119
|
+
curl -fsS -o copy.mp4 -H "Authorization: Bearer ${API_KEY}" "$object"
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Errors
|
|
123
|
+
|
|
124
|
+
RPC error bodies carry `{code,error,status}`. The SDK throws `BackplaneError` with `code`, `message`, and `status`. MCP tool failures set `isError` and carry `{code,message,status}` in `structuredContent`. MCP transport and JSON-RPC protocol failures use their protocol-defined envelopes.
|
|
125
|
+
|
|
126
|
+
| Code | RPC status | Caller action |
|
|
127
|
+
| --- | --- | --- |
|
|
128
|
+
| INVALID_ARGUMENT | 400 | Correct the arguments. |
|
|
129
|
+
| UNAUTHORIZED | 401 | Send the bot key as a bearer token. |
|
|
130
|
+
| FORBIDDEN | 403 | Use the loopback URL and port, and send no Origin header. |
|
|
131
|
+
| NOT_FOUND | 404 | Check the endpoint path. A download of a missing object also returns this code. |
|
|
132
|
+
| METHOD_NOT_ALLOWED | 405 | Use the method named in the `Allow` header. |
|
|
133
|
+
| ALREADY_EXISTS | 409 | Choose a different ID or edit the existing row. |
|
|
134
|
+
| REVISION_CONFLICT | 409 | Read the current version before deciding whether to retry. |
|
|
135
|
+
| PAYLOAD_TOO_LARGE | 413 | Keep `/rpc` and `/mcp` requests under 1 MiB. Stream larger files through `/vfs/object`. |
|
|
136
|
+
| BUSY | 503 | Retry with backoff. |
|
|
137
|
+
| COMMIT_UNCERTAIN | 500 | Inspect the persisted value before issuing another write. |
|
|
138
|
+
| STORAGE_ERROR | 500 | Inspect the store and filesystem. |
|
|
139
|
+
| INTERNAL_ERROR | 500 | Retry once. Report repeated failures with the daemon log. |
|
|
140
|
+
| DSON_REQUIRED | 422 equivalent in an MCP tool result | Repeat the read with DSON encoding. |
|
|
141
|
+
|
|
142
|
+
## Local curl and MCP
|
|
143
|
+
|
|
144
|
+
With `API_KEY` in the shell environment, curl can inspect the RPC schema or populate a cache key.
|
|
145
|
+
|
|
146
|
+
```sh
|
|
147
|
+
curl -fsS -X POST -H "Authorization: Bearer ${API_KEY}" http://127.0.0.1:43127/rpc/schema
|
|
148
|
+
curl -fsS -H "Authorization: Bearer ${API_KEY}" http://127.0.0.1:43127/rpc \
|
|
149
|
+
--json '{"className":"cache","methodName":"set","args":[{"app":"shop","tenant":"acme","bucket":"catalog"},"currency","EUR"]}'
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Configure the agent's Streamable HTTP transport with endpoint `http://127.0.0.1:43127/mcp` and the same Authorization header. Tool discovery lists the ten cache and document operations and `vfs.put`, `vfs.get`, `vfs.head`, `vfs.list` and `vfs.delete`, each with its input schema. For example, call `cache.get` with these arguments.
|
|
153
|
+
|
|
154
|
+
```json
|
|
155
|
+
{"scope":{"app":"shop","tenant":"acme","bucket":"catalog"},"key":"currency"}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
The result is available as `structuredContent.value`. A native value that would lose information in JSON requires `resultEncoding: "dson"` on the read. The value then contains a `dson` string. Shared references, cycles, dates, binary and bigint values can require this mode. MCP keyed document operations accept a string, number, or a tagged bigint such as `{"bigint":"9007199254740993"}`. The tag is also accepted as `document.id` on insert, which returns the tag for a bigint ID. Reading such a document with `resultEncoding: "dson"` preserves the native ID. Conditional MCP writes take `ifRevision` at the top level alongside `scope` and `key` or `id`. Ordinary MCP writes accept JSON. RPC supports DSON for reads and writes. The VFS tools exchange object content as a string: `encoding` selects `utf8`, the default, or `base64` for binary. A `utf8` read of bytes that are not valid UTF-8 fails with `INVALID_ARGUMENT`.
|
|
159
|
+
|
|
160
|
+
## Configuration
|
|
161
|
+
|
|
162
|
+
| Setting | Meaning |
|
|
163
|
+
| --- | --- |
|
|
164
|
+
| `API_KEY` | Required bot key. Use printable ASCII without whitespace. Every holder may access every tenant. |
|
|
165
|
+
| `PORT` | Listener port, default 43127. The host is fixed. |
|
|
166
|
+
| `BACKPLANE_DATA_DIR` | Data root, default `./var/data` relative to the daemon working directory. |
|
|
167
|
+
|
|
168
|
+
App, tenant and bucket identifiers accept 1 to 48 valid UTF-8 bytes. Cache keys and file keys accept 1 to 1,024 valid UTF-8 bytes. Stop the service with SIGTERM or SIGINT. To back up the whole service, stop writers, shut down the daemon, then copy the data root. An application's own authentication determines which tenant it passes to the service.
|
|
169
|
+
|
|
170
|
+
## Development
|
|
171
|
+
|
|
172
|
+
Install the versions in `mise.toml`, then run `make setup` and `make verify`. The latter runs lint, type checking, real storage and protocol tests, coverage, and a packed-consumer test across Node.js and Bun. The sources, tests and verification scripts are TypeScript. The strict compiler checks all three, so lint fails when a test or script calls the API with the wrong types. The packed-consumer test needs `curl`, `lsof` and npm on the `PATH`. Use `make start` for the Node.js daemon or `make start RUNTIME=bun` for Bun. `make status`, `make log` and `make stop` control the source-tree daemon.
|
|
173
|
+
|
|
174
|
+
In a Git working tree, `make gate` runs the vendored defuss-vae verifier. Its review and documentation prompts apply to the current source fingerprint. Storage and transport decisions are in [ARCH.md](ARCH.md).
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
----------- BUNDLED DEPENDENCIES -----------
|
|
2
|
+
|
|
3
|
+
## defuss-db@3.1.0
|
|
4
|
+
License: MIT
|
|
5
|
+
By: Aron Homberg
|
|
6
|
+
|
|
7
|
+
> MIT License
|
|
8
|
+
>
|
|
9
|
+
> Copyright (c) 2026 Aron Homberg
|
|
10
|
+
>
|
|
11
|
+
> Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
12
|
+
> of this software and associated documentation files (the "Software"), to deal
|
|
13
|
+
> in the Software without restriction, including without limitation the rights
|
|
14
|
+
> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
15
|
+
> copies of the Software, and to permit persons to whom the Software is
|
|
16
|
+
> furnished to do so, subject to the following conditions:
|
|
17
|
+
>
|
|
18
|
+
> The above copyright notice and this permission notice shall be included in all
|
|
19
|
+
> copies or substantial portions of the Software.
|
|
20
|
+
>
|
|
21
|
+
> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
22
|
+
> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
23
|
+
> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
24
|
+
> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
25
|
+
> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
26
|
+
> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
27
|
+
> SOFTWARE.
|
|
28
|
+
|
|
29
|
+
---------------------------------------
|
|
30
|
+
|
|
31
|
+
## defuss-search@0.5.0
|
|
32
|
+
License: MIT
|
|
33
|
+
By: Aron Homberg
|
|
34
|
+
|
|
35
|
+
> MIT License
|
|
36
|
+
>
|
|
37
|
+
> Copyright (c) 2026 Aron Homberg
|
|
38
|
+
>
|
|
39
|
+
> Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
40
|
+
> of this software and associated documentation files (the "Software"), to deal
|
|
41
|
+
> in the Software without restriction, including without limitation the rights
|
|
42
|
+
> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
43
|
+
> copies of the Software, and to permit persons to whom the Software is
|
|
44
|
+
> furnished to do so, subject to the following conditions:
|
|
45
|
+
>
|
|
46
|
+
> The above copyright notice and this permission notice shall be included in all
|
|
47
|
+
> copies or substantial portions of the Software.
|
|
48
|
+
>
|
|
49
|
+
> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
50
|
+
> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
51
|
+
> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
52
|
+
> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
53
|
+
> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
54
|
+
> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
55
|
+
> SOFTWARE.
|
|
56
|
+
|
|
57
|
+
---------------------------------------
|
|
58
|
+
|
|
59
|
+
## defuss-vectorsearch@0.4.0
|
|
60
|
+
License: MIT
|
|
61
|
+
By: Aron Homberg
|
|
62
|
+
|
|
63
|
+
> MIT License
|
|
64
|
+
>
|
|
65
|
+
> Copyright (c) 2019 - 2026 Aron Homberg
|
|
66
|
+
>
|
|
67
|
+
> Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
68
|
+
> of this software and associated documentation files (the "Software"), to deal
|
|
69
|
+
> in the Software without restriction, including without limitation the rights
|
|
70
|
+
> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
71
|
+
> copies of the Software, and to permit persons to whom the Software is
|
|
72
|
+
> furnished to do so, subject to the following conditions:
|
|
73
|
+
>
|
|
74
|
+
> The above copyright notice and this permission notice shall be included in all
|
|
75
|
+
> copies or substantial portions of the Software.
|
|
76
|
+
>
|
|
77
|
+
> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
78
|
+
> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
79
|
+
> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
80
|
+
> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
81
|
+
> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
82
|
+
> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
83
|
+
> SOFTWARE.
|