From b6c6cc8295df1b8a80c970e530680fc1fee25301 Mon Sep 17 00:00:00 2001 From: "Dr. Stefan Flemming" Date: Tue, 27 Oct 2026 00:59:57 +0100 Subject: [PATCH] feat: TypeScript client for Node, with a scriptable fake hub A service in front of a hub needs four things: start a flow, follow it, read what a detached run produced, and decide approvals. This is that surface, plus the part a gateway cannot test without: a fake hub that speaks the same service from the same .proto files and can be scripted into every failure a real hub produces. Errors carry the hub's own class (chain-error-kind), a coarse family, and reachedHub, which separates a refused connection from a hub that reports a dependency as down. Both arrive as gRPC UNAVAILABLE, and a gateway that shows 'service not reachable' for the second one lies to its users. The .proto files are carried verbatim and loaded at runtime, so no generated code can drift from the contract; two guards hold the copies in place, and a skew suite runs the same client against a real hub binary. 32 hermetic tests plus 4 against a real hub. Signed-off-by: Dr. Stefan Flemming --- .gitignore | 4 + LICENSE | 201 ++++ README.md | 139 +++ package-lock.json | 363 ++++++ package.json | 42 + proto/CHECKSUMS | 4 + proto/chain/v1/common.proto | 59 + proto/chain/v1/federation.proto | 482 ++++++++ proto/chain/v1/hub.proto | 1756 ++++++++++++++++++++++++++++++ proto/chain/v1/module.proto | 45 + scripts/sync-proto.mjs | 40 + src/client.ts | 478 ++++++++ src/errors.ts | 234 ++++ src/fake_hub.ts | 668 ++++++++++++ src/index.ts | 44 + src/payload.ts | 204 ++++ src/proto.ts | 111 ++ test/client_against_fake.test.ts | 277 +++++ test/errors.test.ts | 105 ++ test/payload.test.ts | 74 ++ test/proto_copy.test.ts | 51 + test/real_hub.test.ts | 127 +++ tsconfig.json | 21 + tsconfig.test.json | 10 + 24 files changed, 5539 insertions(+) create mode 100644 .gitignore create mode 100644 LICENSE create mode 100644 README.md create mode 100644 package-lock.json create mode 100644 package.json create mode 100644 proto/CHECKSUMS create mode 100644 proto/chain/v1/common.proto create mode 100644 proto/chain/v1/federation.proto create mode 100644 proto/chain/v1/hub.proto create mode 100644 proto/chain/v1/module.proto create mode 100644 scripts/sync-proto.mjs create mode 100644 src/client.ts create mode 100644 src/errors.ts create mode 100644 src/fake_hub.ts create mode 100644 src/index.ts create mode 100644 src/payload.ts create mode 100644 src/proto.ts create mode 100644 test/client_against_fake.test.ts create mode 100644 test/errors.test.ts create mode 100644 test/payload.test.ts create mode 100644 test/proto_copy.test.ts create mode 100644 test/real_hub.test.ts create mode 100644 tsconfig.json create mode 100644 tsconfig.test.json diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..360e2f7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +node_modules/ +dist/ +build-test/ +*.tgz diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..ea0aac9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for describing the origin of the Work and + reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may accept and charge a + fee for, acceptance of support, warranty, indemnity, or other + liability obligations and/or rights consistent with this License. + However, in accepting such obligations, You may act only on Your + own behalf and on Your sole responsibility, not on behalf of any + other Contributor, and only if You agree to indemnify, defend, + and hold each Contributor harmless for any liability incurred by, + or claims asserted against, such Contributor by reason of your + accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2026 Dr. Stefan Flemming (Flemming.AI) + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md new file mode 100644 index 0000000..ac28e02 --- /dev/null +++ b/README.md @@ -0,0 +1,139 @@ +# chain-client-sdk-ts + +TypeScript client for a Ch∆In hub, for Node 20 and newer. It covers +what a service in front of a hub needs: start a flow, follow it, ask +what became of a detached run, list and decide approvals. + +The package ships the `chain.v1` `.proto` files verbatim from the +platform repo and loads them at runtime, so there is no generated code +that can drift from the contract. + +```bash +npm install chain-client-sdk-ts # not published yet: use a path or git dependency +``` + +## Running a flow + +```ts +import { ChainClient, asText } from 'chain-client-sdk-ts'; + +const client = new ChainClient({ + address: '127.0.0.1:50051', + token: process.env.CHAIN_TOKEN, + project: 'helloeco', +}); + +const result = await client.submit({ + flowYaml: await readFile('flows/verbrauchsausweis.yaml', 'utf8'), + inputs: { consumption: { json: { kwh: 15400 } } }, + idempotencyKey: stripeEvent.id, +}); + +console.log(asText(result.outputs.report)); +``` + +Inputs: a string is text, an object tagged `json`, `bytes` or `file` +is that kind, and any other object is sent as `json`. Outputs come +back tagged, with `asText`, `asJson` and `asBytes` as readers. + +`idempotencyKey` is the caller's word for "this is the same request as +before". A second submit with a key the hub has already seen returns +the first run instead of starting a second one, which is what a +payment webhook that retries needs. + +## Following a run + +```ts +for await (const event of client.submitStream({ flowYaml, inputs })) { + if (event.type === 'stepStarted') log.info({ step: event.step }, 'step started'); + if (event.type === 'result') deliver(event.result.outputs); +} +``` + +A run that fails throws a `ChainError` out of the loop, so the events +seen so far stay valid and a failure is never a silent end of stream. + +Detached runs (`detach: true`) return once they have an id; +`getStatus`, `getResult` and `cancel` take it from there. + +## Approvals + +```ts +const waiting = await client.listApprovals({ project: 'helloeco' }); +await client.decideApproval({ + approvalId: waiting[0].approvalId, + approve: true, + reviewer: 'aussteller@example.org', +}); +``` + +The hub records who decided and why. Where it can verify an identity +behind the token, that identity wins over the `reviewer` field, so the +field is a fallback and not a claim the hub trusts blindly. + +## Errors + +Every failure is a `ChainError` with four fields worth branching on: + +| Field | What it says | +|-------|--------------| +| `kind` | the hub's own class: `flow_rejected`, `step_failed`, `step_timeout`, `approval_rejected`, `approval_timeout`, `unavailable`, `overloaded`, `precondition`, `not_found`, `conflict`, `forbidden`, `unauthenticated`, `timeout`, `cancelled`, `internal`, or `unknown` from a newer hub | +| `family` | the coarse branch: `unreachable`, `rejected`, `failed`, `overloaded`, `auth`, `timeout`, `cancelled`, `internal` | +| `reachedHub` | whether the hub answered at all | +| `retryable` | true for `unreachable`, `overloaded` and `timeout` | + +`reachedHub` is the field that keeps a gateway honest. A refused +connection and a hub reporting "the model host is down" both arrive as +gRPC `UNAVAILABLE`; only the second one carries a class, so only the +second one is the hub's own answer. The class travels in the +`chain-error-kind` trailer of every error response (hub 0.25 and +newer) and in `StreamError.kind` inside a stream. + +## Testing against a fake hub + +The package carries a scriptable hub that speaks the same service from +the same `.proto` files, so a gateway's tests need no hub binary, no +module and no model. + +```ts +import { FakeHub } from 'chain-client-sdk-ts/fake-hub'; + +const hub = new FakeHub(); +const address = await hub.start(); + +hub.succeeds({ report: 'zugestellt' }); // the next run finishes +hub.fails('overloaded', 'too many runs'); // the next run is refused +hub.waitsForApproval({ prompt: 'Zustellen?' }); // the next run waits +await hub.stop(); // the hub is gone +await hub.restart(); // it comes back, without the running runs +``` + +`hub.submits` and `hub.decisions` record what arrived, so a test can +assert on what the gateway sent, not only on what it got back. +`restart()` models what today's hub really does: run state lives in +memory and is lost, while approvals live in SQLite and survive. A +gateway has to treat "approval still pending after a restart" as a run +it must start again. + +## Development + +```bash +npm install +npm test # type-check, then the hermetic suites +npm run build # dist/ + +# the skew gate: the same client against a real hub binary +CHAIN_BIN=../fai_chain/target/debug/chain npm test + +# refresh the contract after a platform change +node scripts/sync-proto.mjs ../fai_chain +``` + +`npm test` runs the fake-hub suite, the payload and error-class unit +tests, and the guard that the `.proto` copies still match both their +recorded hashes and the platform repo. The real-hub suite skips itself +when no binary is there. + +## License + +Apache 2.0. Copyright Dr. Stefan Flemming, Flemming.AI. diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..ff3f4cf --- /dev/null +++ b/package-lock.json @@ -0,0 +1,363 @@ +{ + "name": "chain-client-sdk-ts", + "version": "0.1.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "chain-client-sdk-ts", + "version": "0.1.0", + "license": "Apache-2.0", + "dependencies": { + "@grpc/grpc-js": "^1.14.0", + "@grpc/proto-loader": "^0.8.0" + }, + "devDependencies": { + "@types/node": "^22.10.0", + "typescript": "^5.9.0" + }, + "engines": { + "node": ">=20.11" + } + }, + "node_modules/@grpc/grpc-js": { + "version": "1.14.6", + "resolved": "https://registry.npmjs.org/@grpc/grpc-js/-/grpc-js-1.14.6.tgz", + "integrity": "sha512-SgC/B3/VZ8lTyOZ4Cwk6f1skWhmkNAaVfiX90qd5u1rRXGKk1//8FTUEN9GvOUq7rfWIqAYkA3CoyumYVpOS6g==", + "license": "Apache-2.0", + "dependencies": { + "@grpc/proto-loader": "^0.8.0", + "@js-sdsl/ordered-map": "^4.4.2" + }, + "engines": { + "node": ">=12.10.0" + } + }, + "node_modules/@grpc/proto-loader": { + "version": "0.8.1", + "resolved": "https://registry.npmjs.org/@grpc/proto-loader/-/proto-loader-0.8.1.tgz", + "integrity": "sha512-wtF6h+DY6M3YaDBPAmvuuA6jV8Sif9MjtOI5euKFWRgCDl5PeDpPsHR9u2l6St5ceY8AZgoNDww5+HvEsXFsGg==", + "license": "Apache-2.0", + "dependencies": { + "lodash.camelcase": "^4.3.0", + "long": "^5.0.0", + "protobufjs": "^7.5.5", + "yargs": "^17.7.2" + }, + "bin": { + "proto-loader-gen-types": "build/bin/proto-loader-gen-types.js" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/@js-sdsl/ordered-map": { + "version": "4.4.2", + "resolved": "https://registry.npmjs.org/@js-sdsl/ordered-map/-/ordered-map-4.4.2.tgz", + "integrity": "sha512-iUKgm52T8HOE/makSxjqoWhe95ZJA1/G1sYsGev2JDKUSS14KAgg1LHb+Ba+IPow0xflbnSkOsZcO08C7w1gYw==", + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/js-sdsl" + } + }, + "node_modules/@protobufjs/aspromise": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz", + "integrity": "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==", + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/base64": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@protobufjs/base64/-/base64-1.1.2.tgz", + "integrity": "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==", + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/codegen": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.5.tgz", + "integrity": "sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==", + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/eventemitter": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@protobufjs/eventemitter/-/eventemitter-1.1.1.tgz", + "integrity": "sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==", + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/fetch": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@protobufjs/fetch/-/fetch-1.1.1.tgz", + "integrity": "sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==", + "license": "BSD-3-Clause", + "dependencies": { + "@protobufjs/aspromise": "^1.1.1" + } + }, + "node_modules/@protobufjs/float": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/@protobufjs/float/-/float-1.0.2.tgz", + "integrity": "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==", + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/path": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@protobufjs/path/-/path-1.1.2.tgz", + "integrity": "sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==", + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/pool": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@protobufjs/pool/-/pool-1.1.0.tgz", + "integrity": "sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==", + "license": "BSD-3-Clause" + }, + "node_modules/@protobufjs/utf8": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.2.tgz", + "integrity": "sha512-b1UQwcEZ4yCnMCD8DAL1VlbvBJE9/IX4FTIp7BG1xYpf29SLazLSrqUkj4w7Y5y7cCVP6E5tcqqcI0xemPkHug==", + "license": "BSD-3-Clause" + }, + "node_modules/@types/node": { + "version": "22.20.5", + "resolved": "https://registry.npmjs.org/@types/node/-/node-22.20.5.tgz", + "integrity": "sha512-U2+DNr+wSjpsTS/wZGYHq7GcwfuSmKiKvoPvK22zwTlRhU91yOniN4qRR5KhIjvif7ysw/dz/hKmfDH0Ris4aA==", + "license": "MIT", + "dependencies": { + "undici-types": "~6.21.0" + } + }, + "node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/ansi-styles": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", + "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", + "license": "MIT", + "dependencies": { + "color-convert": "^2.0.1" + }, + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/chalk/ansi-styles?sponsor=1" + } + }, + "node_modules/cliui": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz", + "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==", + "license": "ISC", + "dependencies": { + "string-width": "^4.2.0", + "strip-ansi": "^6.0.1", + "wrap-ansi": "^7.0.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/color-convert": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", + "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", + "license": "MIT", + "dependencies": { + "color-name": "~1.1.4" + }, + "engines": { + "node": ">=7.0.0" + } + }, + "node_modules/color-name": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", + "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", + "license": "MIT" + }, + "node_modules/emoji-regex": { + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz", + "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==", + "license": "MIT" + }, + "node_modules/escalade": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz", + "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==", + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/get-caller-file": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz", + "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==", + "license": "ISC", + "engines": { + "node": "6.* || 8.* || >= 10.*" + } + }, + "node_modules/is-fullwidth-code-point": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz", + "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/lodash.camelcase": { + "version": "4.3.0", + "resolved": "https://registry.npmjs.org/lodash.camelcase/-/lodash.camelcase-4.3.0.tgz", + "integrity": "sha512-TwuEnCnxbc3rAvhf/LbG7tJUDzhqXyFnv3dtzLOPgCG/hODL7WFnsbwktkD7yUV0RrreP/l1PALq/YSg6VvjlA==", + "license": "MIT" + }, + "node_modules/long": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz", + "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==", + "license": "Apache-2.0" + }, + "node_modules/protobufjs": { + "version": "7.6.6", + "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.6.6.tgz", + "integrity": "sha512-dYDWdjSl5RNb7SgPxGQcRU+GtvP7s2fpkrY0r432PcOIaZ0/rBcxEZnQN67iJhFuQiVw754JDoPruPCNdGsbjg==", + "hasInstallScript": true, + "license": "BSD-3-Clause", + "dependencies": { + "@protobufjs/aspromise": "^1.1.2", + "@protobufjs/base64": "^1.1.2", + "@protobufjs/codegen": "^2.0.5", + "@protobufjs/eventemitter": "^1.1.1", + "@protobufjs/fetch": "^1.1.1", + "@protobufjs/float": "^1.0.2", + "@protobufjs/path": "^1.1.2", + "@protobufjs/pool": "^1.1.0", + "@protobufjs/utf8": "^1.1.1", + "@types/node": ">=13.7.0", + "long": "^5.3.2" + }, + "engines": { + "node": ">=12.0.0" + } + }, + "node_modules/require-directory": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz", + "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/string-width": { + "version": "4.2.3", + "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz", + "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==", + "license": "MIT", + "dependencies": { + "emoji-regex": "^8.0.0", + "is-fullwidth-code-point": "^3.0.0", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/undici-types": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", + "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", + "license": "MIT" + }, + "node_modules/wrap-ansi": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz", + "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==", + "license": "MIT", + "dependencies": { + "ansi-styles": "^4.0.0", + "string-width": "^4.1.0", + "strip-ansi": "^6.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/chalk/wrap-ansi?sponsor=1" + } + }, + "node_modules/y18n": { + "version": "5.0.8", + "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", + "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==", + "license": "ISC", + "engines": { + "node": ">=10" + } + }, + "node_modules/yargs": { + "version": "17.7.3", + "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.3.tgz", + "integrity": "sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g==", + "license": "MIT", + "dependencies": { + "cliui": "^8.0.1", + "escalade": "^3.1.1", + "get-caller-file": "^2.0.5", + "require-directory": "^2.1.1", + "string-width": "^4.2.3", + "y18n": "^5.0.5", + "yargs-parser": "^21.1.1" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/yargs-parser": { + "version": "21.1.1", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz", + "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==", + "license": "ISC", + "engines": { + "node": ">=12" + } + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..6f70d3c --- /dev/null +++ b/package.json @@ -0,0 +1,42 @@ +{ + "name": "chain-client-sdk-ts", + "version": "0.1.0", + "description": "TypeScript client for a Ch∆In hub: run flows, follow them, decide approvals.", + "license": "Apache-2.0", + "author": "Dr. Stefan Flemming ", + "type": "module", + "engines": { + "node": ">=20.11" + }, + "main": "./dist/index.js", + "types": "./dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + }, + "./fake-hub": { + "types": "./dist/fake_hub.d.ts", + "default": "./dist/fake_hub.js" + } + }, + "files": [ + "dist", + "proto", + "README.md", + "LICENSE" + ], + "scripts": { + "build": "tsc -p tsconfig.json", + "test": "tsc -p tsconfig.test.json && node --test --test-timeout=30000 \"build-test/test/*.test.js\"", + "check": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit" + }, + "dependencies": { + "@grpc/grpc-js": "^1.14.0", + "@grpc/proto-loader": "^0.8.0" + }, + "devDependencies": { + "@types/node": "^22.10.0", + "typescript": "^5.9.0" + } +} diff --git a/proto/CHECKSUMS b/proto/CHECKSUMS new file mode 100644 index 0000000..457d47f --- /dev/null +++ b/proto/CHECKSUMS @@ -0,0 +1,4 @@ +98a68dd39de4f98d965baf87eca60acc53bb393bd90ae9feb2c07b98071823d9 chain/v1/common.proto +b38ade1faa50cd5e645b040001b3d2e32b287b128556694837a1a30083b8416e chain/v1/hub.proto +1b2742775d3abe0bcbdcb4a56c14b434e8547f672ea10a7f648ad14c7e14bef7 chain/v1/module.proto +47d3af9df026a40f5f5a76311965f719e3ceb49ad944c4393e02158a0bdb1873 chain/v1/federation.proto diff --git a/proto/chain/v1/common.proto b/proto/chain/v1/common.proto new file mode 100644 index 0000000..6b6d4c8 --- /dev/null +++ b/proto/chain/v1/common.proto @@ -0,0 +1,59 @@ +syntax = "proto3"; + +package chain.v1; + +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; + +// A unique identifier for a flow invocation (UUIDv7). +message InvocationId { + string value = 1; +} + +// A reference to a capability requested by a flow step. +// +// Example: namespace="text", name="extract", version_req="^1" +message CapabilityRef { + string namespace = 1; + string name = 2; + string version_req = 3; +} + +// A typed value passed between flow steps. +message Payload { + oneof kind { + string text = 1; + google.protobuf.Struct json = 2; + Bytes bytes = 3; + FileRef file = 4; + } +} + +message Bytes { + string mime_type = 1; + bytes data = 2; +} + +message FileRef { + string uri = 1; // file://, s3://, etc. + string mime_type = 2; + uint64 size_bytes = 3; + string sha256 = 4; +} + +// Standard error shape for hub and module responses. +message ChainError { + Code code = 1; + string message = 2; + string details = 3; + + enum Code { + UNKNOWN = 0; + INVALID_INPUT = 1; + CAPABILITY_NOT_SUPPORTED = 2; + PERMISSION_DENIED = 3; + RESOURCE_EXHAUSTED = 4; + DEADLINE_EXCEEDED = 5; + INTERNAL = 6; + } +} diff --git a/proto/chain/v1/federation.proto b/proto/chain/v1/federation.proto new file mode 100644 index 0000000..a482d62 --- /dev/null +++ b/proto/chain/v1/federation.proto @@ -0,0 +1,482 @@ +syntax = "proto3"; + +package chain.v1; + +import "google/protobuf/empty.proto"; +import "chain/v1/common.proto"; + +// Hub-to-hub federation. A satellite hub opens one persistent +// HTTP/2 connection to a primary hub. Within that connection, +// the four streams below multiplex. +// +// Phase 1.0 ships Control + Invoke + Blob + Events. A fifth +// stream (`Stream` for bidirectional streaming caps, e.g. live +// audio) is reserved for Phase 1.1; the slot stays free in the +// service so adding it is purely additive. +// +// See `docs/architecture/federation.md` for the full design, +// security model, and threat-model summary. +service Federation { + // Long-lived bidirectional Control stream. First two messages + // exchanged are always Hello (satellite -> primary) and Accept + // (primary -> satellite). Subsequent messages multiplex over + // the same channel: advertisements, withdrawals, heartbeats, + // renames, and cert renewals. + // + // Disconnect signals shutdown: the primary withdraws every + // capability advertised by this satellite. The satellite is + // expected to reconnect with exponential backoff. + rpc Control(stream ControlMessage) returns (stream ControlMessage); + + // Reserved stub. Cross-hub dispatch does NOT use a unary RPC: + // the satellite dials outbound (NAT-friendly) and is the gRPC + // client, so the primary cannot open a call back into it. Real + // dispatch flows over the Control stream via DispatchCall / + // DispatchResult (FED-06). This RPC stays declared only so the + // service slot is stable; it returns UNIMPLEMENTED. + // + // The satellite resolves `capability_id` against its **local** + // registry; unknown capabilities return CAPABILITY_NOT_SUPPORTED. + // The wire never carries executable content — only inputs. + rpc Dispatch(DispatchRequest) returns (DispatchResponse); + + // Bidirectional chunked binary transfer. Used for `bytes` + // payloads above `federation.blob_threshold` (default 1 MiB). + // The first message on either side is BlobOpen describing the + // operation ("upload" or "download"); subsequent messages + // carry data or end-of-stream / error markers. + rpc Blob(stream BlobChunk) returns (stream BlobChunk); + + // Server-streaming relay of audit + step events from a + // satellite to the primary. The primary's Studio uses this to + // show live progress of remote flow runs and to surface + // approval-pending notices from remote steps. + rpc Events(EventsRequest) returns (stream RelayedEvent); +} + +// ---- Control multiplex ---------------------------------------------- + +// All Control-stream messages share this envelope so a single +// gRPC stream can carry the full state-machine vocabulary +// without needing one stream per message kind. +message ControlMessage { + oneof kind { + HelloMessage hello = 1; + AcceptMessage accept = 2; + AdvertiseMessage advertise = 3; + WithdrawMessage withdraw = 4; + HeartbeatMessage heartbeat = 5; + HeartbeatAck heartbeat_ack = 6; + RenameMessage rename = 7; + CertRenewRequest cert_renew_request = 8; + CertRenewResponse cert_renew_response = 9; + // FED-06: cross-hub dispatch multiplexes over this same + // satellite-opened stream (the satellite is the gRPC client, + // so the primary cannot open a unary call back into it). The + // primary sends DispatchCall down; the satellite executes + // locally and sends DispatchResult back up, correlated by + // request_id. + DispatchCall dispatch_call = 10; + DispatchResult dispatch_result = 11; + } +} + +// Primary -> satellite: please execute this capability call. The +// request_id correlates the matching DispatchResult flowing back +// up the same Control stream. +message DispatchCall { + // Per-call correlation id (UUIDv7), primary-generated. Unique + // within the connection's in-flight window. + string request_id = 1; + // The call to execute. Reuses the unary message shape. + DispatchRequest request = 2; +} + +// Satellite -> primary: the result of a prior DispatchCall. +message DispatchResult { + // Echoes the originating DispatchCall.request_id. + string request_id = 1; + // Outputs / error / timing for the executed call. + DispatchResponse response = 2; +} + +// First message a satellite sends after the TLS handshake. The +// primary either responds with Accept (success) or closes the +// stream with a status carrying a friendlyError-shaped detail +// (no overlap on wire_version, bootstrap token rejected, display +// name already in use, etc.). +message HelloMessage { + // Immutable Hub Instance UUID (UUIDv7) generated at the + // satellite's first `chain init`. Persisted in `~/.chain/hub-id`. + // The federation cert's subject embeds this value; it can + // never change without a fresh `chain init`. + string hub_id = 1; + + // Operator-chosen display name (e.g. "satellite-a"). May be + // changed later via the Rename message. The primary refuses + // a Hello whose display_name collides with another connected + // satellite. + string display_name = 2; + + // Ch∆In binary version, informational. Lets the primary record + // satellite versions for operator visibility without coupling + // them to wire compatibility (which is governed by + // wire_versions_supported below). + string hub_version = 3; + + // Set of federation wire-protocol versions the satellite can + // speak. The primary picks the highest element also in its own + // supported set. Empty list is treated as `[1]`. + repeated uint32 wire_versions_supported = 4; + + // Set of module-WIT contract versions the satellite supports. + // Per-capability advertisements carry their own wit_version; + // this is the satellite's overall envelope. + repeated string wit_versions_supported = 5; + + // Single-use bootstrap token, present only on the *very first* + // connect when the satellite has no federation cert yet. The + // primary validates against its issued-but-unused token store, + // issues a 24h federation cert in the Accept message, and + // marks the token consumed. + // + // Empty string on every subsequent connect — the satellite + // identifies itself with the mTLS cert and this field is + // ignored. + string bootstrap_token = 6; + + // Optional region tag the satellite claims at first enrollment. + // Signed into the issued cert by the primary; future connects + // read region from the cert, not from this field. + string region = 7; + + // PEM-encoded PKCS#10 CSR generated by the satellite on first + // enrollment, with its immutable hub UUID in the subject CN. The + // primary's CA signs it (pinning that UUID) and returns the leaf + // cert in `AcceptMessage.issued_cert_pem`. Empty on reconnects + // once the satellite already holds a valid cert. + string csr_pem = 8; +} + +// First message the primary sends in response to Hello. Closes +// the handshake; the connection is then ready for advertisements +// and dispatch. +message AcceptMessage { + // Wire version both sides will use for the lifetime of this + // connection. Highest common element of + // `hello.wire_versions_supported` and the primary's own list. + uint32 wire_version_chosen = 1; + + // Primary's own identity, so the satellite can record it in + // its routing table and audit log. + string primary_hub_id = 2; + string primary_display_name = 3; + string primary_hub_version = 4; + repeated uint32 primary_wire_versions_supported = 5; + + // Federation cert PEM issued by the primary. Present on + // enrollment connect (when hello.bootstrap_token was set) and + // on cert renewals (in response to CertRenewRequest). Empty + // on plain reconnect with an existing valid cert. + string issued_cert_pem = 6; + + // ISO-8601 expiry of `issued_cert_pem`. Empty when no cert + // issued in this message. + string cert_expires_at = 7; +} + +// Capability advertisement. Sent after Accept and any time the +// satellite's local registry changes (install, uninstall, +// disable). Replaces — does not append to — any prior +// advertisement from this connection. +message AdvertiseMessage { + repeated CapabilityAdvertisement capabilities = 1; +} + +// One advertised capability. The primary indexes by +// (capability_id, origin_uuid) — never by display name, so a +// rename never invalidates the index. +message CapabilityAdvertisement { + // Fully qualified id, e.g. "text.extract@1.4.2". SemVer + // version follows the @. + string capability_id = 1; + + // UUID of the hub that *originally* provides this capability. + // Distinct from the connection's sender UUID when an + // intermediate hub is re-advertising (mesh phases). + string origin_uuid = 2; + + // Display name of the origin hub at advertisement time. + // Operator-friendly label; the primary stores the UUID for + // routing and resolves to name for display. + string origin_name = 3; + + // BGP-style path: ordered list of hub UUIDs the advertisement + // travelled through, **oldest first**. The receiving hub + // refuses to accept an advertisement whose route already + // contains its own UUID (loop prevention). + repeated string route = 4; + + // Optional region tag inherited from the origin's cert. + // Empty when the origin advertises no region. + string region = 5; + + // Quality metrics measured at the origin hub. Used by the + // primary for `auto:healthiest` / `auto:lowest_rtt` selection. + Quality quality = 6; + + // Permission strings the satellite-side module declared, + // informational only. Each satellite enforces its own + // ceiling locally; the primary cannot widen permissions + // remotely. + repeated string permissions = 7; + + // Module WIT contract version. The primary refuses to + // dispatch into a satellite advertising a WIT version it does + // not support. + string wit_version = 8; + + // Ch∆In binary version that loaded this capability at the + // origin. Informational. + string hub_version = 9; +} + +// Quality metrics piggybacked on every advertisement update. +// Numbers measured at the origin hub; an end-to-end RTT field +// (sum across hops) lands in Phase 1.2 when mesh +// re-advertisement ships. +message Quality { + // 50th percentile round-trip time over the recent window. + uint32 rtt_p50_ms = 1; + // 95th percentile round-trip time over the recent window. + uint32 rtt_p95_ms = 2; + // Successful invocations / total in last 30 min. 1.0 = all + // succeeded. 0.0 = all failed (or no data). + float success_rate_30m = 3; + // Currently in-flight streams (rough load indicator). + uint32 streams_active = 4; + // Per-satellite hard limit on concurrent streams. Lets the + // primary calculate utilisation for least-loaded selection. + uint32 streams_capacity = 5; +} + +// Withdraw one or more capabilities. Equivalent to sending an +// Advertise without these entries, but lighter on the wire when +// only a small subset changed. +message WithdrawMessage { + // Fully-qualified ids to withdraw. + repeated string capability_ids = 1; + // Only advertisements from this origin UUID are affected. + string origin_uuid = 2; +} + +// Liveness + RTT probe. Cadence configurable; default 10 s with +// jitter. +message HeartbeatMessage { + // Monotonic per-connection nonce so the Ack can be matched. + uint64 nonce = 1; + // Milliseconds since epoch on the satellite at send time. + int64 satellite_time_ms = 2; +} + +message HeartbeatAck { + uint64 nonce = 1; + // Milliseconds since epoch on the primary at ack time. + int64 primary_time_ms = 2; +} + +// Operator-driven rename. Display name changes do not require a +// new cert because the UUID stays the same. The primary +// re-validates name uniqueness within its federation, updates +// its routing table, and emits an audit event tying old and new +// names to the unchanged UUID. +message RenameMessage { + string new_display_name = 1; +} + +// Cert renewal. The satellite generates a CSR locally, embedding +// its immutable hub UUID in the subject. The primary's CA +// signing logic MUST verify that the CSR subject's hub UUID +// matches the connection's existing mTLS cert UUID — a stolen +// cert otherwise lets an attacker renew into a different UUID +// and bypass revocation. +message CertRenewRequest { + // PEM-encoded PKCS#10 certificate signing request. + string csr_pem = 1; +} + +message CertRenewResponse { + // PEM-encoded fresh cert on success. Empty on refusal. + string cert_pem = 1; + // ISO-8601 expiry of `cert_pem`. Empty when refused. + string expires_at = 2; + // Human-readable refusal reason. Empty on success. + string error = 3; +} + +// ---- Invoke --------------------------------------------------------- + +// Dispatch one capability call. The dispatcher at the primary +// resolves a flow step's `use:` + `on:` into one DispatchRequest +// addressed at the chosen satellite's UUID. +message DispatchRequest { + // Fully qualified capability id (matching the advertised id). + string capability_id = 1; + + // UUID of the hub expected to execute. The recipient verifies + // that this matches its own UUID OR (Phase 1.2+ mesh) routes + // the call along the next hop toward the target UUID. Required. + string target_hub_id = 2; + + // Inputs in the same Payload shape Hub::Submit uses, so + // module-side conversion is identical to local invocation. + map inputs = 3; + + // UUIDv7 correlation id shared across hops + audit logs on + // both sides for a single cross-hub call. Lets `chain admin + // events` reconstruct the full trace later. + string trace_id = 4; + + // Per-call nonce; the satellite rejects replays within a + // sliding window (default 60 s) to defend against captured- + // call replay attacks. + string nonce = 5; + + // Operator-friendly caller identity (e.g. token name, user + // login) for the satellite's local audit attribution. Empty + // for anonymous primary configurations. + string caller_name = 6; + + // Optional region requirement. When set, the satellite must + // refuse the call if its own region tag doesn't match + // (case-insensitive exact match in 1.0; hierarchical match + // lands in 1.1). + string region_required = 7; +} + +message DispatchResponse { + // Outputs on success. + map outputs = 1; + // Error shape on failure. The `code` mirrors common.ChainError + // codes; the satellite maps its local ChainError to this wire. + ChainError error = 2; + // Wall-clock duration of the actual module invocation at the + // satellite, in milliseconds. Excludes federation transport. + uint32 duration_ms = 3; + // UUID of the hub that actually executed. Same as + // `target_hub_id` in 1.0; in Phase 1.2+ relayed calls may + // surface a different value when an intermediate hub had a + // local copy. + string executed_at_hub_id = 4; +} + +// ---- Blob ------------------------------------------------------------ + +// One chunk on the bidirectional Blob stream. The opening +// message describes the operation; subsequent messages carry +// payload bytes or end-of-stream / error markers. +// +// Chunk-size convention: 256 KiB. Receivers MUST NOT assume a +// fixed chunk size — HTTP/2 framing and senders may differ. +message BlobChunk { + oneof kind { + BlobOpen open = 1; + bytes data = 2; + BlobEof eof = 3; + BlobError error = 4; + } +} + +message BlobOpen { + // "upload" or "download". Other values reserved for future + // expansion (e.g. "resume", "verify"). + string operation = 1; + + // Sha256 (lowercase hex) when known up-front. Required for + // downloads (which sha256 to fetch); empty for streaming + // uploads where the sha is computed during the transfer. + string sha256 = 2; + + // Total payload size in bytes when known up-front; 0 means + // "streaming with unknown size". + uint64 size_bytes = 3; + + // Mime type metadata propagated from the source `Bytes` payload. + string mime_type = 4; + + // HMAC-signed blob reference URL for downloads. The primary + // verifies signature, expiry, and audience (target hub UUID) + // before honouring the open. Empty on uploads. + string signed_ref = 5; +} + +message BlobEof { + // Final sha256 of the assembled blob. The receiver verifies + // this against its running hash; a mismatch closes the stream + // with a BlobError and discards the partial. + string sha256 = 1; + // Final byte count actually transferred. Lets the receiver + // sanity-check against any prior `BlobOpen.size_bytes`. + uint64 size_bytes = 2; +} + +message BlobError { + // Stable kebab-cased code so callers can map to friendlyError + // copy. Known values: "size-cap-exceeded", "hash-mismatch", + // "expired", "audience-mismatch", "permission-denied", + // "internal". + string code = 1; + // Free-form diagnostic text. + string message = 2; +} + +// ---- Events relay --------------------------------------------------- + +// Subscription request from a primary that wants to receive +// remote-step events. The satellite first replays up to +// `backfill` historical events then streams live ones. +message EventsRequest { + // Optional filter on the origin hub UUID. Empty = receive + // everything the satellite relays. + string filter_hub_id = 1; + // Optional glob-style filter on event_type strings. + // E.g. ["step.*", "approval.*"]. Empty = no filter. + repeated string event_types = 2; + // Backfill count before switching to live tail. Defaults to + // 50 when 0; capped at 1000 by the satellite. + uint32 backfill = 3; +} + +// One forwarded event. The event payload mirrors LoggedEvent's +// shape so existing Studio renderers handle it without +// branching. The origin annotation lets Studio show "from +// satellite X" badges. +message RelayedEvent { + // UUID of the hub the event originated at. + string origin_hub_id = 1; + // Display name of the origin hub at relay time. May be stale + // (operator just renamed) — receivers resolve UUID -> name + // from their routing table as the source of truth. + string origin_display_name = 2; + + // Event payload. Shape mirrors hub.proto's LoggedEvent so + // Studio doesn't need a second renderer; the fields listed + // here are the wire stable subset. + string event_id = 3; + string timestamp = 4; + string event_type = 5; + string flow_execution = 6; + string invocation_id = 7; + string flow_name = 8; + string step_id = 9; + string module_name = 10; + string module_version = 11; + int64 duration_ms = 12; + string error = 13; + // Free-form JSON. Capped at the satellite's + // `federation.limits.event_detail_max_bytes` (default 32 KiB) + // before forwarding to defend against exfiltration via large + // detail blobs. + string detail = 14; + string caller_name = 15; +} diff --git a/proto/chain/v1/hub.proto b/proto/chain/v1/hub.proto new file mode 100644 index 0000000..8519776 --- /dev/null +++ b/proto/chain/v1/hub.proto @@ -0,0 +1,1756 @@ +syntax = "proto3"; + +package chain.v1; + +import "google/protobuf/empty.proto"; +import "chain/v1/common.proto"; + +// The Hub service is what CLI clients, web UIs, or other tools talk to. +service Hub { + // Submit a flow for execution. + rpc Submit(SubmitRequest) returns (SubmitResponse); + + // Submit a flow and follow its execution live (added 1.1). Same + // request as unary Submit; the response is a stream of step markers, + // ephemeral module events (host.emit-event), and finally the result + // or an error. Works over native gRPC and gRPC-Web (server + // streaming). Unary Submit is unchanged for clients that don't care. + rpc SubmitStream(SubmitRequest) returns (stream SubmitStreamEvent); + + // List modules known to this hub. + rpc ListModules(google.protobuf.Empty) returns (ModuleList); + + // Detached-invocation lifecycle (added 1.1). Only invocations + // submitted with detach=true are tracked; results are retained under + // hard operator limits (size/count/TTL) and NOT persisted across a + // hub restart. + rpc GetInvocationStatus(InvocationId) returns (InvocationStatus); + rpc GetInvocationResult(InvocationId) returns (SubmitResponse); + rpc CancelInvocation(InvocationId) returns (CancelInvocationResponse); + + // List every tracked detached invocation (newest-first) for a + // monitor surface — Studio's detached-runs list. Returns an empty + // list (not an error) when detached invocations are disabled. + rpc ListInvocations(google.protobuf.Empty) returns (InvocationList); + + // Liveness / readiness probe. + rpc Health(google.protobuf.Empty) returns (HealthStatus); +} + +// HubAdmin exposes administrative operations on the hub: inspect +// installed modules, query the event log, manage saved flows. +// +// Calls to HubAdmin from external clients are unauthenticated in +// Phase 0/0.5 (localhost trust). Phase 1+ adds bearer-token / mTLS +// auth on this surface. Calls from within modules require the +// `hub:` permission scope (read / install / admin). +service HubAdmin { + // List capabilities provided by all installed modules. + rpc ListCapabilities(google.protobuf.Empty) returns (CapabilityList); + + // Return full manifest data for one installed module. + rpc ModuleInfo(ModuleInfoRequest) returns (ModuleInfoResponse); + + // Check whether a module is allowed a given permission under the + // operator's policy. Returns the decision plus the reason. + rpc CheckPermission(CheckPermissionRequest) returns (CheckPermissionResponse); + + // Read a slice of the event log, newest first. + rpc EventLog(EventLogRequest) returns (EventLogResponse); + + // Server-streaming variant of EventLog. The hub first emits up + // to `limit` historical events (newest-last so clients receive + // them in chronological order), then keeps the stream open and + // forwards every freshly-appended event in real time. Reads + // require the Read scope when auth is on. + rpc StreamEvents(StreamEventsRequest) returns (stream LoggedEvent); + + // Saved-flow management. A saved flow is a YAML file under + // /flows/.yaml; it can be re-run by name later. + rpc SaveFlow(SaveFlowRequest) returns (SaveFlowResponse); + rpc DeleteFlow(DeleteFlowRequest) returns (DeleteFlowResponse); + rpc ListFlows(google.protobuf.Empty) returns (FlowList); + rpc RunSavedFlow(RunSavedFlowRequest) returns (SubmitResponse); + + // Return the parsed structure of a saved flow (declared + // inputs + their type tags) so a client can render an + // input form before calling RunSavedFlow. + rpc GetFlowDefinition(GetFlowDefinitionRequest) returns (FlowDefinition); + + // List the shared hub's project registry (`general` first) — + // the lightweight labels that group flows, runs, approvals and + // audit events. Only `open` and `protected` projects appear: + // sealed projects are their own hub instance and are never + // known to a shared hub (docs/architecture/projects.md). + // Studio's workspace switcher reads this list. + rpc ListProjects(google.protobuf.Empty) returns (ProjectList); + + // Search the bundled (and Phase 1+: federated) store index for + // modules matching a query. + rpc SearchStore(SearchStoreRequest) returns (StoreSearchResponse); + + // List the configured module stores (operator config `stores:`) + // plus the implicit bundled seed, for the Studio store manager. + rpc ListStores(ListStoresRequest) returns (ListStoresResponse); + + // Register a new module store and merge its index into the live + // store so its modules become searchable + installable immediately. + rpc AddStore(AddStoreRequest) returns (AddStoreResponse); + + // Drop a configured store by name and rebuild the live index + // without it. The bundled seed cannot be removed. + rpc RemoveStore(RemoveStoreRequest) returns (RemoveStoreResponse); + + // Install a module from a .chain bundle (local path or http(s) URL). + rpc InstallModule(InstallModuleRequest) returns (InstallModuleResponse); + + // Same install, with live progress. Emits an update per phase and, + // during the download, as bytes arrive; the last message carries + // either the finished response or the error. Clients that only need + // the outcome keep using the unary InstallModule above — this exists + // so a waiting operator can see that a slow download is progressing + // rather than hung. + rpc InstallModuleStream(InstallModuleRequest) + returns (stream InstallProgressEvent); + + // Remove an installed module by name. Wipes the module + // directory and re-scans the registry; writes a + // `module.uninstalled` audit event. Surfaced by the Studio + // module sheet's "Uninstall" affordance. + rpc UninstallModule(UninstallModuleRequest) returns (UninstallModuleResponse); + + // Fetch a module's README (or other docs) and return the + // markdown content as a string. The hub knows how to + // authenticate against the configured registry — Studio + // doesn't need to handle credentials. Studio's Store detail + // sheet renders the result inline. + rpc FetchModuleDocs(FetchModuleDocsRequest) returns (FetchModuleDocsResponse); + + // Read the inline-docs (MODULE.md / MODULE..md) of an + // installed module from disk. No network fetch, no provider- + // specific URL probing — the docs ship in the .chain bundle and + // live next to module.wasm on disk after install. Returns an + // empty body when the module is installed but ships no inline + // docs; Studio uses that to hide the docs button entirely. + rpc GetInstalledModuleDocs(GetInstalledModuleDocsRequest) returns (GetInstalledModuleDocsResponse); + + // Invoke an installed Studio plugin's `theme` hook. Returns + // the plugin's proposed Material 3 ColorScheme for the + // brightness the caller asked for ("light" or "dark"). The + // first end-to-end RPC of the Studio-plugin subsystem; the + // `translate` and `output-view` hooks get their own RPCs as + // the matching Studio surfaces ship. + rpc InvokePluginTheme(InvokePluginThemeRequest) returns (InvokePluginThemeResponse); + + // Invoke an installed Studio plugin's `translate` hook. + // The first user surface that consumes this is Studio's + // FaiEnBadge — when an operator has a translate plugin + // installed, server-supplied English text (MCP tool + // descriptions, n8n endpoint names) gets translated + // on-the-fly into the active locale instead of carrying + // the honest-but-rough [EN] badge. + rpc InvokePluginTranslate(InvokePluginTranslateRequest) returns (InvokePluginTranslateResponse); + + // List system.approval@^0 entries, optionally filtered by status. + rpc ListApprovals(ListApprovalsRequest) returns (ApprovalList); + + // Reviewer decision on a pending approval. `decision` selects + // approve / reject; `reviewer` and `reason` supply the audit + // attribution. The flow that posted the approval resumes (or + // fails) on the next polling tick. + rpc DecideApproval(DecideApprovalRequest) returns (DecideApprovalResponse); + + // Walk the event-log hash chain and return whether tampering + // was detected. Surfaced by the CLI as `chain admin verify-events` + // and by Studio's health page. + rpc VerifyEventChain(google.protobuf.Empty) returns (VerifyEventChainResponse); + + // Wipe every audit event and seed the log with a single + // `chain.reset` marker. Refused on `beta` / `production` for + // compliance — only callable on `local` / `dev`. Surfaced by + // the CLI as `chain admin events clear`. + rpc ClearEventLog(ClearEventLogRequest) returns (ClearEventLogResponse); + + // Read the operator's `default_scope:` (the ordered list of + // provider segments the bare-form capability resolver tries + // when a flow names a capability without `/` + // prefix). Always returns the current in-memory copy. + rpc GetDefaultScope(google.protobuf.Empty) returns (DefaultScopeResponse); + + // Replace the operator's `default_scope:`. The hub validates + // each entry against the namespace catalog before writing to + // disk. Returns the resulting snapshot so the client can + // refresh its UI in one round-trip. + rpc SetDefaultScope(SetDefaultScopeRequest) returns (DefaultScopeResponse); + + // Re-read `auth.tokens:` from operator config + env vars and + // atomically swap the live token store. Used by operators to + // rotate tokens without restarting the daemon. Returns the + // new token count. Errors if the new config is invalid (env + // var missing, duplicate secret, no scopes, …) — the + // existing store stays in place so a botched rotation can't + // lock the operator out. + rpc ReloadAuth(google.protobuf.Empty) returns (ReloadAuthResponse); + + // Read-only snapshot of the authentication policy as persisted + // in the operator config, for operator surfaces (Studio + // Settings → Security). Never carries secret material: token + // entries expose the env-var NAME and whether that variable is + // currently set — never the value; the jwt-rs256 validator + // exposes its key SOURCE (inline / file path), never the key. + // Admin-scoped like ReloadAuth. + rpc AuthStatus(google.protobuf.Empty) returns (AuthStatusResponse); + + // Assemble the guided-setup plan for the given answers — a pure + // computation (chain_core::guided_setup::assemble), no state + // change, nothing written. Lets a GUI render the setup preview + // over its existing hub connection instead of spawning the CLI: + // on macOS that subprocess can be the app's first file-system + // touch and trigger a permission prompt BEFORE the operator has + // seen what would be set up — the wrong order for trust. Apply + // remains a deliberate separate step. + rpc PlanSetup(PlanSetupRequest) returns (PlanSetupResponse); + + // List host services declared in the operator config. Each + // entry carries name + endpoint; reachability is operator-side + // (on-demand `chain service status` or Studio probe). + rpc ListServices(google.protobuf.Empty) returns (ServiceList); + + // Declare a new host service in the operator config. Fails with + // ALREADY_EXISTS when a service of that name is configured. + rpc DeclareService(DeclareServiceRequest) returns (DeclareServiceResponse); + + // Compare the running hub's version against the channel release + // manifest. Surfaced by the CLI as `chain update check` and by + // Studio's Doctor page as a "v0.x.y available" pill. Network + // failures are returned as `manifest_reachable=false` rather + // than gRPC errors so Studio can render gracefully when the + // release host is unreachable (air-gapped, offline laptop). + rpc CheckUpdate(google.protobuf.Empty) returns (CheckUpdateResponse); + + // Active channel + per-channel daemon status. Lets Studio's + // settings page render which channel is current and whether + // each daemon is up. Mirrors the CLI's `fai daemon status`. + rpc ChannelStatus(google.protobuf.Empty) returns (ChannelStatusResponse); + + // Filesystem locations the daemon owns: log file, db file, + // modules dir, flows dir, config file. Studio's Doctor page + // surfaces these so operators on Windows (who never touch + // a shell) can open them via the OS file manager. + rpc DaemonPaths(google.protobuf.Empty) returns (DaemonPathsResponse); + + // Configured MCP servers + their last-discovery report. + // Studio's MCP-clients editor renders the result. Mirrors + // `chain mcp list` on the CLI. + rpc ListMcpClients(google.protobuf.Empty) returns (ListMcpClientsResponse); + + // Re-run discovery against every configured MCP server and + // update the *live* store-index in place. Synthetic entries + // for tools the server no longer exposes are dropped. + // Mirrors `chain mcp refresh` but operates on the running + // daemon — Studio doesn't need to ask the operator to + // restart anything. + rpc RefreshMcpClients(google.protobuf.Empty) returns (ListMcpClientsResponse); + + // Persist a new MCP server in `~/.chain/config.yaml` and + // re-run discovery. Returns the resulting list (same shape + // as ListMcpClients) so Studio can repaint in one round-trip. + rpc AddMcpClient(McpClientConfigEntry) returns (ListMcpClientsResponse); + + // Remove an MCP server by name and re-run discovery so its + // synthetic capabilities disappear from the store. + rpc RemoveMcpClient(RemoveMcpClientRequest) returns (ListMcpClientsResponse); + + // n8n bridges. Same shape as the MCP client RPCs above — + // every active workflow surfaces as `n8n..`. + rpc ListN8nEndpoints(google.protobuf.Empty) returns (ListN8nEndpointsResponse); + rpc RefreshN8nEndpoints(google.protobuf.Empty) returns (ListN8nEndpointsResponse); + rpc AddN8nEndpoint(N8nEndpointConfigEntry) returns (ListN8nEndpointsResponse); + rpc RemoveN8nEndpoint(RemoveN8nEndpointRequest) returns (ListN8nEndpointsResponse); + + // Read-only system-AI status. Lets Studio render the + // "configure in Settings" affordance when the feature is + // off, and the privacy-mode badge when it is on. + rpc SystemAiStatus(google.protobuf.Empty) returns (SystemAiStatusResponse); + + // Ask the system AI a one-shot question. Errors carry the + // failure category (disabled / env-missing / http / parse) + // so Studio can map them to the inline-fix-hint copy from + // `docs/architecture/system-ai.md`. + rpc AskAi(AskAiRequest) returns (AskAiResponse); + + // Persist a new system-AI configuration. Updates the live + // hub state AND writes back to ~/.chain/config.yaml so the + // change survives daemon restart. Used by Studio's settings + // editor. Returns the resulting status (same shape as + // SystemAiStatus) so the UI can refresh in one round-trip. + rpc UpdateSystemAi(UpdateSystemAiRequest) returns (SystemAiStatusResponse); + + // Probe a system-AI configuration with a tiny ping. The + // request body carries the *draft* config the operator is + // editing — Test Connection works *before* Save so the user + // doesn't have to commit a broken config to validate it. + // An all-empty body falls back to the live in-memory config. + rpc TestSystemAi(TestSystemAiRequest) returns (AskAiResponse); + + // List the models the configured provider exposes via + // `GET /v1/models`. Studio's editor populates the model + // dropdown from this. Same draft-vs-live semantics as + // TestSystemAi. + rpc ListSystemAiModels(TestSystemAiRequest) returns (ListSystemAiModelsResponse); + + // Pull (download + install) an Ollama model via the native + // /api/pull endpoint. Synchronous, may take minutes for + // large models. Same error-kind taxonomy as AskAi. + rpc PullSystemAiModel(PullSystemAiModelRequest) returns (PullSystemAiModelResponse); + + // Same pull, with live progress. A model pull moves gigabytes, so + // the unary form above leaves a person waiting minutes with nothing + // to look at. Emits Ollama's own status plus byte counts per layer, + // ending in the response. + rpc PullSystemAiModelStream(PullSystemAiModelRequest) + returns (stream PullProgressEvent); + + // Drop every cached System-AI explanation. Surfaced in + // Studio's Settings so operators can force a clean slate + // without changing model/privacy mode (which also flushes). + rpc ClearSystemLlmCache(google.protobuf.Empty) returns (ClearSystemLlmCacheResponse); + + // Drop a single cached entry by prompt — the same prompt + // Studio sent in AskAi. Used by the "Regenerate" button so + // the next AskAi call falls through to the live provider. + rpc ForgetCachedExplanation(AskAiRequest) returns (google.protobuf.Empty); + + // Detected host hardware tier + summary line. Studio's + // System-AI editor uses this to mark models as "may be slow + // on your hardware" without requiring a benchmark. + rpc HardwareInfo(google.protobuf.Empty) returns (HardwareInfoResponse); + + // Bundled curated model database (quality tier, parameter + // count, recommended-for tier, notes). Studio merges this + // with the live `/v1/models` listing for richer chips. The + // `last_reviewed` field tells the operator how stale the + // curation is. + rpc ListSystemAiCuratedModels(google.protobuf.Empty) + returns (ListSystemAiCuratedModelsResponse); + + // Federation (primary side). Issue a single-use bootstrap + // token enrolling a named satellite (`chain admin satellites + // peer-add`), and list the satellites currently connected + // (`chain admin satellites list`). + rpc IssueBootstrapToken(IssueBootstrapTokenRequest) + returns (IssueBootstrapTokenResponse); + rpc ListSatellites(google.protobuf.Empty) returns (SatelliteList); + // Revoke a satellite by UUID (`chain admin satellites revoke`): + // drops any live connection and refuses future connects even + // with a still-valid cert. Persisted across restarts. + rpc RevokeSatellite(RevokeSatelliteRequest) returns (google.protobuf.Empty); +} + +message RevokeSatelliteRequest { + // Immutable hub UUID of the satellite to revoke. + string hub_id = 1; +} + +message SubmitRequest { + // The flow definition as raw YAML. + bytes flow_yaml = 1; + // Named input values for the flow. + map inputs = 2; + // When true (added 1.1), Submit returns immediately with the + // invocation id and the flow keeps running in the background. Poll + // GetInvocationStatus / fetch GetInvocationResult, or follow it live + // via SubmitStream. Only detached invocations are retained; unary + // detach=false is unchanged (synchronous, stateless). + bool detach = 3; + // Project slug this run belongs to (added phase 2). Overrides the + // flow YAML's `project:`; empty → the flow's project, then + // `general`. Every audit event, approval and detached row from this + // run is stamped (and hashed) with it. Grouping/filtering only — + // not tenancy. + string project = 4; + // Caller's key for "this is the same request as before" (added + // in hub 0.25). A second submit carrying a key the hub has already seen + // returns the first run instead of starting a second one, which is + // what a payment webhook that retries needs. At most 128 printable + // ASCII characters; empty means no deduplication. Scoped to the + // project. + string idempotency_key = 5; +} + +message SubmitResponse { + InvocationId invocation_id = 1; + // Named output values produced by the flow. + map outputs = 2; +} + +// One event in a SubmitStream (added 1.1). Exactly one field is set. +message SubmitStreamEvent { + oneof event { + StepStarted step_started = 1; + StepFinished step_finished = 2; + ModuleEvent module_event = 3; + // Terminal success — identical to the unary SubmitResponse. + SubmitResponse final_result = 4; + // Terminal failure — the flow (or a step) errored. + StreamError error = 5; + } +} + +message StepStarted { + string step = 1; + // Capability the step resolved to, e.g. "text.extract". + string capability = 2; +} + +message StepFinished { + string step = 1; + bool ok = 2; + int64 duration_ms = 3; +} + +// An ephemeral event a module emitted via host.emit-event (WIT 1.1). +// Never written to the audit log. +message ModuleEvent { + // The step whose module emitted this. + string step = 1; + // Module-defined label, e.g. "progress" / "token". + string name = 2; + // Event body. + Payload payload = 3; +} + +message StreamError { + string message = 1; + // Machine-readable error class, the same vocabulary as the + // `chain-error-kind` trailer of a unary error (added in hub 0.25): + // flow_rejected, step_failed, step_timeout, approval_rejected, + // approval_timeout, unavailable, overloaded, precondition, + // not_found, conflict, internal. Empty from a hub older than 0.25. + string kind = 2; +} + +// Lifecycle of a detached invocation (added 1.1). +message InvocationStatus { + enum Phase { + PHASE_UNKNOWN = 0; + PENDING = 1; + RUNNING = 2; + SUCCEEDED = 3; + FAILED = 4; + CANCELLED = 5; + } + Phase phase = 1; + // Step currently executing (RUNNING), empty otherwise. + string current_step = 2; + // RFC 3339 timestamps; finished_at empty until the flow ends. + string started_at = 3; + string finished_at = 4; + // Error message when phase == FAILED, empty otherwise. + string error = 5; +} + +message CancelInvocationResponse { + // True if a running invocation was signalled to cancel; false if it + // was already finished or unknown. + bool cancelled = 1; +} + +// One row in the detached-runs monitor list. +message InvocationEntry { + string invocation_id = 1; + InvocationStatus status = 2; + // Flow name this invocation is running, empty when unknown. + string flow_name = 3; + // Project slug the run was stamped with (`general` when none). + string project = 4; +} + +message InvocationList { + // Tracked detached invocations, newest-first by start time. + repeated InvocationEntry invocations = 1; + // Whether the operator enabled detached invocations + // (`detached.enabled`). Lets monitor UIs distinguish "feature + // off" from "on, but no runs yet" instead of guessing (added + // additively; absent = false on pre-1.1 hubs). + bool detached_enabled = 2; +} + +message ModuleList { + repeated ModuleSummary modules = 1; +} + +message ModuleSummary { + string name = 1; + string version = 2; + repeated CapabilityRef provides = 3; +} + +message HealthStatus { + enum State { + UNKNOWN = 0; + SERVING = 1; + NOT_SERVING = 2; + } + State state = 1; + string detail = 2; +} + +// HubAdmin messages + +message CapabilityList { + repeated CapabilityEntry capabilities = 1; +} + +message CapabilityEntry { + // Full capability identifier, e.g. "text.extract". + string capability = 1; + // Capability version (semver). + string version = 2; + // Module providing this capability. + string module_name = 3; + // Module's own version. + string module_version = 4; + // Where this capability comes from. Studio gates install + // affordances on this — only "wasm" caps have a bundle to + // install. Empty string is treated as "wasm" for + // backwards-compat with older hubs. + // "wasm" — declared by an installed WASM module + // "builtin" — implemented in the hub itself + // (e.g. system.approval) + // "federated" — discovered from an external MCP/n8n server; + // not installable via the module-store path + string kind = 5; + // Publisher identity (provider segment) of the capability. + // Always set on registered capabilities. "fai" for legacy + // bundles that didn't declare a provider. For federated + // capabilities, this is the operator's service `name:` + // (e.g. "deepwiki", "bmds.spark"). Wire-level addition for + // the naming convention; see + // `docs/reference/capability-namespaces.yaml`. + string provider = 6; + // Transport that delivers this capability to the Hub. + // Distinct from `kind` (which captures the install-vs-builtin + // distinction) — `source_kind` records HOW the Hub reaches + // the implementation. Studio renders this as a badge next to + // the capability name. + // "bundle" — installed .chain WASM bundle + // "system" — Hub built-in (fai.system/*) + // "mcp" — federated via an MCP service + // "n8n" — federated via an n8n endpoint + // "temporal" — federated via a Temporal service (e.g. SPARK) + // "webhook" — reserved for Phase 1+ + string source_kind = 7; + // Whether the version on this capability is advisory rather + // than a hard contract. True for federated capabilities whose + // upstream service does not honour semver; operator pins are + // labels, not guarantees. Studio renders a warning badge. + bool version_advisory = 8; +} + +message ModuleInfoRequest { + string module_name = 1; +} + +message ModuleInfoResponse { + string name = 1; + string version = 2; + repeated CapabilityRef provides = 3; + // Permission strings exactly as declared in module.yaml. + repeated string permissions = 4; + // Filesystem location the module was loaded from. + string directory = 5; + // MIME allow-list for bytes-shaped inputs, copied verbatim + // from `module.yaml`'s `accepts_mime:` field. Empty means + // "no declared restriction". Studio uses this to pre-filter + // the OS file-picker so operators don't pick a file the + // module would reject. + repeated string accepts_mime = 6; + // Capabilities this module advisorily expects to be available, + // copied from module.yaml's optional `consumes:` list. Empty + // means "this is a leaf module with no declared dependencies". + // Studio surfaces "you'll also want these installed" hints + // based on this list; the hub does NOT enforce. + repeated ConsumedCapability consumes = 7; + // Declared inputs the module's invoke function accepts. The + // editor uses this to render per-field input ports with their + // canonical names + types and i18n tooltips. Empty when the + // manifest declares no inputs (rare; usually means the module + // is a pure data source). + repeated ModuleField inputs = 8; + // Declared outputs the module produces. The editor uses this + // to render one output port per declared field instead of + // collapsing every downstream reference into a single anchor. + repeated ModuleField outputs = 9; +} + +message ConsumedCapability { + // Capability name, e.g. "llm.chat". + string capability = 1; + // Semver range constraint, e.g. "^0". Empty = any version. + string version = 2; + // Free-form rationale from the manifest's `why:` field. + string why = 3; +} + +// One declared input or output field on a module. Carries the +// type descriptor (text / json / bytes / file) and a locale → +// description map for tooltips. The map is keyed by IETF locale +// tag ("en", "de", "ja", …) so callers pick their active +// locale with a single lookup + "en" fallback. +message ModuleField { + // Field name, e.g. "prompt" or "model_endpoint". + string name = 1; + // Type descriptor: one of text / json / bytes / file. + string type = 2; + // Locale → description. Empty map = no description declared + // (schema_version 1/2 manifests, or v3 manifests that left + // the field in shorthand form). + map description = 3; +} + +message CheckPermissionRequest { + string module_name = 1; + // Permission string in `: ` form. + string permission = 2; +} + +message CheckPermissionResponse { + bool allowed = 1; + // Human-readable reason. Empty when allowed. + string reason = 2; +} + +message EventLogRequest { + // Maximum number of events to return. Defaults to 100 when 0. + int32 limit = 1; + // Optional event_type filter; when empty, all types are returned. + repeated string event_types = 2; + // Optional project filter (slug). Empty = all projects. Scopes + // the audit view to one project — the per-project compliance + // export use case (`chain admin events --project`). + string project = 3; +} + +message EventLogResponse { + repeated LoggedEvent events = 1; +} + +message StreamEventsRequest { + // Backfill size before the stream switches to live updates. + // 0 means "no backfill, only new events". Defaults to 50 when + // unset; capped at 1000 server-side to bound the initial buffer. + int32 backfill = 1; + // Optional event_type filter; when empty, all types are streamed. + // The filter applies to both the backfill prefix and the live + // tail. + repeated string event_types = 2; + // Optional project filter (slug). Empty = all projects. Applies + // to both the backfill prefix and the live tail. + string project = 3; +} + +message LoggedEvent { + string event_id = 1; + string timestamp = 2; + string event_type = 3; + string flow_execution = 4; + string invocation_id = 5; + string flow_name = 6; + string step_id = 7; + string module_name = 8; + string module_version = 9; + int64 duration_ms = 10; + string error = 11; + // Free-form JSON-string carrying event-type-specific fields: + // input/output sizes, model digest, sha256, etc. Empty when + // the event type has no structured detail. Studio renders + // this as a code block in the audit drill-down. + string detail = 12; + // Operator-friendly name of the token whose holder + // triggered this event. Empty when the call was anonymous + // (auth.tokens: not configured), when the event was emitted + // by hub-internal code (boot housekeeping, federation + // discovery), or when the row pre-dates the audit- + // attribution migration (0006). + string caller_name = 13; + // Project slug the run was stamped with (`general` when the + // run carried no explicit project). Bound into the V4 audit + // hash, so the attribution is tamper-evident. Empty on rows + // pre-dating the project migration (0008). + string project = 14; +} + +message SaveFlowRequest { + // Flow name (used as the file name with .yaml extension). + string name = 1; + // Flow YAML content. + bytes flow_yaml = 2; + // If false and a flow with this name exists, return AlreadyExists. + bool overwrite = 3; +} + +message SaveFlowResponse { + string name = 1; + bool created = 2; +} + +message DeleteFlowRequest { + string name = 1; +} + +message DeleteFlowResponse { + string name = 1; +} + +message FlowList { + repeated FlowSummary flows = 1; +} + +message FlowSummary { + string name = 1; + // Path on disk relative to the saved-flows directory. + string path = 2; + // Bytes on disk. + int64 size_bytes = 3; + // Verbatim `use:` strings of every step in the flow, + // deduplicated and sorted. Lets a GUI client decide whether + // a flow is currently runnable (every entry resolves to an + // installed module) without parsing the YAML itself. + repeated string required_capabilities = 4; + // The flow's own top-level `project:` slug; empty when the + // YAML has none (a run then lands in the caller's project, + // then `general`). The file wins on mismatch — same semantics + // as the CLI (docs/architecture/projects.md). + string project = 5; + // True when the file still carries the bundled-sample header — + // it arrived via the hub's sample import, not from an operator. + // Clients mark and group these so examples are never mistaken + // for real work. Deleting the header claims the flow. + bool sample = 6; +} + +// One registered project (shared-hub registry row). Sealed +// projects never appear here — they are their own hub instance. +message ProjectInfo { + // Stable lowercase-kebab identifier stamped onto every run. + string slug = 1; + // Human display name (renamable without touching history). + string name = 2; + // Accent colour (hex, e.g. "#8b7cf6") for UI marking. Empty + // when unset. + string color = 3; + // Free-form description. Empty when unset. + string description = 4; + // Protection level: "open" (pure label) or "protected" + // (logically separated — no hard process barrier; the honest + // wording every UI must keep). + string isolation = 5; + // ISO-8601 UTC creation timestamp. + string created_at = 6; +} + +message ProjectList { + // All registered projects, `general` first, then by display + // name (case-insensitive). + repeated ProjectInfo projects = 1; +} + +message RunSavedFlowRequest { + string name = 1; + map inputs = 2; + // Project slug override (added phase 2); empty → the saved flow's + // own `project:`, then `general`. + string project = 3; +} + +message GetFlowDefinitionRequest { + string name = 1; +} + +// Parsed shape of a saved flow. Currently surfaces only the +// declared inputs — that is what Studio needs to render its +// run-flow form. Fields can grow (steps, outputs) without +// breaking older clients. +message FlowDefinition { + string name = 1; + // Declared input keys plus their declared type tag, exactly + // as the flow YAML's `inputs:` section spelled them. Common + // values: "text", "bytes", "json", "file". + repeated FlowInputSpec inputs = 2; +} + +message FlowInputSpec { + // Input key (the name the flow YAML uses). + string name = 1; + // Declared type tag from the flow YAML — opaque string so + // the wire stays stable as the type system grows. + string type = 2; +} + +message SearchStoreRequest { + // Free-text search; matches name, tagline, description, category, tags. + string query = 1; + // Optional category filter. + string category = 2; + // Optional tag filter. + string tag = 3; + // Optional status filter: "published", "alpha", or "planned". + string status = 4; + // Maximum results; defaults to 50 when 0. + int32 limit = 5; + // Exact-match provider segment filter (0.12+). Empty string + // matches any provider. + string provider = 6; + // First-dotted-segment-of-name filter (0.12+). E.g. "text" + // matches text.extract, text.summarize, … but not + // image.classify. Empty matches any namespace. + string namespace = 7; +} + +message StoreSearchResponse { + repeated StoreEntry entries = 1; +} + +message InstallModuleRequest { + // Local path or http(s) URL of the .chain bundle, OR a + // capability name (e.g. "text.extract") resolved via the + // store index. + string source = 1; + // Optional expected SHA-256 hex string for verification. + string expected_sha256 = 2; + // Optional explicit version when `source` is a capability + // name. Ignored for URL / local-path sources (the bundle's + // own manifest dictates the version). Empty string falls + // back to "highest-priority version from the store index". + string version = 3; +} + +message InstallModuleResponse { + string name = 1; + string version = 2; + // Number of capabilities the installed module provides. + int32 capability_count = 3; +} + +// One message in an InstallModuleStream. +message InstallProgressEvent { + oneof event { + // Progress moved, or a phase started or finished. + InstallProgressUpdate update = 1; + // The install succeeded; always the final message. + InstallModuleResponse finished = 2; + // The install failed; always the final message. Carries the same + // text the unary call would have returned as its status message. + string failed = 3; + } +} + +// A single progress observation. +message InstallProgressUpdate { + // Stable phase identifier: "resolve", "download" or "install". + // Clients map it to their own wording; it is not display text. + string phase = 1; + // English fallback label for the phase ("Downloading"). Clients with + // their own translations key off `phase` and ignore this. + string stage = 2; + // Overall progress across all phases, 0..100, monotonic. Absent + // means the extent is not knowable yet — show an indeterminate + // indicator, never a bar parked at zero. + optional float percent = 3; + // Bytes received so far during the download phase. + uint64 bytes_received = 4; + // Total bytes the server announced. Zero means the server sent no + // content-length, so only `bytes_received` is meaningful. + uint64 bytes_total = 5; + // The named phase just finished. + bool phase_done = 6; +} + +message UninstallModuleRequest { + // Module name as the registry knows it. Empty → InvalidArgument. + string name = 1; + // Optional exact version to remove when multiple versions of the + // same `(provider, name)` are installed side-by-side. Empty + // falls back to "remove the highest-version match". + string version = 2; +} + +message UninstallModuleResponse { + string name = 1; + // Version that was removed; "unknown" when the manifest was + // unreadable for some reason but the directory still got wiped. + string version = 2; +} + +message FetchModuleDocsRequest { + // Module name as the store-index knows it. The hub looks up + // its repository URL and tries the well-known raw-README + // paths (Forgejo / GitHub / GitLab style), then any + // `docs_url` override the module declares. + string name = 1; + // Preferred locale code (e.g. "de", "en"). When set, the hub + // first tries `README..md` before falling back to the + // generic `README.md`. Empty string = no locale preference. + string locale = 2; +} + +message FetchModuleDocsResponse { + // Empty on success; otherwise one of: + // "not_found" — module not in the store-index + // "no_docs" — index has no repository or docs URL + // "network" — http error / unreachable + // "auth" — registry returned 401/403 + // "parse" — body was not utf-8 + string error_kind = 1; + // Human-readable detail. On success this is the markdown + // content; on failure a fix hint. + string text = 2; + // The URL the hub fetched from, so Studio can render a + // "View on " link for context. + string source_url = 3; +} + +message GetInstalledModuleDocsRequest { + // Capability id (e.g. `text.extract`) or module-manifest name + // (e.g. `text-extract`). The hub maps capability → module via + // the registry; falls back to treating the name as a + // directory name. + string name = 1; + // Preferred locale code (e.g. "de", "en"). When set and not + // "en", `MODULE..md` is tried first; otherwise the + // generic `MODULE.md` is used. Empty string = no preference. + string locale = 2; +} + +message GetInstalledModuleDocsResponse { + // Markdown body. Empty when the module is installed but ships + // no inline docs — Studio uses this to hide its docs button. + string text = 1; + // Absolute path on the hub host that the body was read from, + // for "loaded from /path/MODULE.md" hints in Studio. Empty + // when text is empty. + string source_path = 2; + // True when the module wasn't installed at all. Distinct from + // "installed but no inline docs" so Studio can show different + // affordances ("install first" vs "no inline docs available"). + bool not_installed = 3; +} + +message InvokePluginThemeRequest { + // Capability name the operator asked for, e.g. + // `studio.theme.solarized`. The hub maps this to the + // installed plugin directory. + string capability = 1; + // "light" or "dark" — the plugin returns a ColorScheme + // for this brightness. Plugins that don't recognise the + // value return PluginError::declined and the hub + // surfaces that as a friendly error. + string brightness = 2; +} + +message InvokePluginTranslateRequest { + // Capability name (e.g. `studio.translate.ollama`). + string capability = 1; + // Text to translate. UTF-8, arbitrary length the plugin + // tolerates. + string text = 2; + // BCP-47 source locale. Empty = let the plugin auto-detect. + string from_locale = 3; + // BCP-47 target locale. Required; the host always knows it. + string to_locale = 4; +} + +message InvokePluginTranslateResponse { + // Translated text. Returns verbatim what the plugin + // emits — no normalisation by the hub. + string translated = 1; +} + +message InvokePluginThemeResponse { + // Echo of the brightness input. Plugins are expected to + // round-trip it; if they don't the client treats that as + // a contract violation. + string brightness = 1; + // 14 ARGB tokens in Material 3 order: + // primary, on_primary, secondary, on_secondary, + // tertiary, on_tertiary, error, on_error, + // surface, on_surface, surface_variant, + // on_surface_variant, outline, outline_variant. + // Studio merges any missing slot (well-behaved plugins + // send all 14) with its built-in fallback before + // applying the scheme. + repeated uint32 tokens = 2; +} + +message ListApprovalsRequest { + // Filter by status. Empty = all. Allowed wire values: + // "pending", "approved", "rejected", "expired". + repeated string statuses = 1; + // Maximum rows; defaults to 100 when 0. + int32 limit = 2; + // Optional project filter (slug). Empty = all projects. + string project = 3; +} + +message ApprovalList { + repeated PendingApprovalEntry entries = 1; +} + +message PendingApprovalEntry { + string approval_id = 1; + string flow_execution = 2; + string flow_name = 3; + string step_id = 4; + string prompt = 5; + // Truncated string preview of the payload the flow handed to + // the approval step, for reviewer context. + string payload_preview = 6; + string created_at = 7; + // Empty when the approval has no timeout. + string expires_at = 8; + // One of "pending", "approved", "rejected", "expired". + string status = 9; + // Empty until decided. + string decided_at = 10; + string decided_by = 11; + string reason = 12; + // Project slug the requesting run was stamped with + // (`general` when the run carried no explicit project). + string project = 13; +} + +message DecideApprovalRequest { + string approval_id = 1; + enum Decision { + DECISION_UNSPECIFIED = 0; + APPROVE = 1; + REJECT = 2; + } + Decision decision = 2; + // Reviewer attribution, recorded in the audit trail. Required. + string reviewer = 3; + // Free-form reason. Required for REJECT, ignored for APPROVE. + string reason = 4; +} + +message DecideApprovalResponse { + string approval_id = 1; + // The new status: "approved" or "rejected". + string status = 2; +} + +message VerifyEventChainResponse { + // Total events scanned. + int64 total = 1; + // Number of events verified before any tamper detection. + // Equal to total on a clean chain. + int64 verified = 2; + // Empty when no tampering was detected; otherwise the + // event_id of the first inconsistent row. + string tampered_at = 3; +} + +message ServiceList { + repeated DeclaredService services = 1; +} + +// Declare a host service in the operator config (`services:`). +// The hub persists it to ~/.chain/config.yaml with the same +// round-trip semantics as the MCP/n8n writers (every other key +// stays intact). Services are read at daemon start, so the +// response says honestly that a restart is required. +message DeclareServiceRequest { + string name = 1; + string endpoint = 2; + // Empty defaults to "/". + string health_path = 3; + repeated string tags = 4; +} + +message DeclareServiceResponse { + // True until the hub learns to hot-reload `services:` — the + // caller should surface "takes effect after a daemon restart". + bool restart_required = 1; +} + +message DeclaredService { + string name = 1; + string endpoint = 2; + // Empty defaults to "/". + string health_path = 3; + repeated string tags = 4; + // Network reach of `endpoint`, classified from its host part + // (no DNS lookups — named hosts other than localhost report + // "unknown"): + // "loopback" — 127.0.0.0/8, ::1, localhost + // "private" — RFC1918 / ULA / link-local ranges + // "public" — any other literal IP + // "unknown" — unparseable, or a hostname we cannot judge + // Empty from pre-0.23 hubs. + string exposure = 5; +} + +message StoreEntry { + string name = 1; + string tagline_en = 2; + string tagline_de = 3; + string description_en = 4; + string description_de = 5; + string category = 6; + repeated string tags = 7; + repeated string requires_capabilities = 8; + repeated string requires_services = 9; + string license = 10; + string repository = 11; + string best_version = 12; + // Status of best_version: "published", "alpha", "planned", or empty. + string status = 13; + bool installed = 14; + // True iff the store-index marks this module as editorially + // featured. Studio renders featured entries in a separate + // strip above the main grid. Curated quarterly in the hub's + // bundled seed.yaml — same review cadence as the curated + // model database. + bool featured = 15; + // Optional URL of a square icon (PNG / SVG, 256px+). + // Studio loads and renders this in the detail sheet's hero + // header in place of the category-derived fallback. Empty + // → fall back to the category icon. + string icon_url = 16; + // Optional screenshot URLs in display order. Studio renders + // them as a horizontally-scrollable strip in the detail + // sheet so operators can see what the module *does* before + // installing. + repeated string screenshot_urls = 17; + // Explicit docs URL override. Empty → hub falls back to the + // well-known raw-README paths against `repository`. + // Use this when the README lives at a non-default branch / + // path or when the docs are a separate Markdown file. + string docs_url = 18; + // Origin of this entry. "native" (downloadable bundle, the + // default for every seed.yaml entry) or "federated" (routes + // through a bridge — MCP, n8n, …). Studio uses the value to + // branch the install action. + string kind = 19; + // Provider id for federated entries. Empty for native. + // For MCP this is the operator's `mcp_clients[].name`. + // Studio renders "via mcp:" so the operator sees + // where a synthetic capability comes from. + string provider = 20; + // Transport delivering this entry's capability. Distinct + // from `kind` (native-vs-federated) — `source_kind` says + // HOW the Hub reaches the implementation. Values mirror + // `CapabilityEntry.source_kind`: + // "bundle" — installed .chain WASM bundle (native entries) + // "mcp" — federated via an MCP service + // "n8n" — federated via an n8n endpoint + // "temporal" — federated via a Temporal service (e.g. SPARK) + // "webhook" — reserved for Phase 1+ + // Empty string falls back to deriving from `kind` for + // pre-0.12 hubs. + string source_kind = 21; + // Name of the store this entry was loaded from: "bundled" for the + // built-in seed, otherwise the operator-added store's name. Distinct + // from source_kind (the transport) — this is the ORIGIN store. Studio + // groups modules by it and shows a "from " label. + string source = 22; + // Canonical, normalized category slug (e.g. "data", "text-language", + // "studio-themes"). The hub maps the free-form `category` onto a + // fixed taxonomy by capability namespace, so different stores using + // different labels ("data" vs "data-processing") land in ONE bucket. + // Studio groups + filters by this, not the raw `category`. Empty + // from pre-0.21 hubs → Studio falls back to `category`. + string canonical_category = 23; + // Human-readable label for `canonical_category` (e.g. "Data & + // Formats"). English; Studio may localize via the slug. + string canonical_category_label = 24; + // How an install of this entry would be verified, given its + // origin store and the operator's CURRENT security policy. The + // hub computes this with the same resolution the install path + // enforces (pinned store key -> trusted publishers -> policy), + // so the display can never disagree with the gate: + // "pinned-key" — verified against the origin store's + // pinned cosign key (or the built-in + // official key for bundled/official) + // "trusted-publishers" — verified against the applicable + // trusted-publisher list + // "unverified" — require_signatures is off; installs + // are NOT signature-checked + // "blocked" — policy requires signatures but no key + // material applies to this source; an + // install would be refused + // "federated" — bridge entry (MCP/n8n/…); no bundle + // signature applies + // Empty from pre-0.23 hubs — clients keep their generic note. + string install_verification = 25; + // Maintainer display strings from the store index (one per + // person/organization). Empty when the index does not specify + // any — clients render an honest "not specified". + repeated string maintainers = 26; + // Where the module's data comes from, for `source.*` capabilities. + // Absent for every other module: a text splitter reaches no + // third-party material and has no provenance to declare. + optional DataSource data_source = 27; +} + +// Provenance of the material a `source.*` module fetches. +// +// Separate from the module's own licence, which covers its code. A +// module can be Apache-2.0 while the corpus it reaches is +// public-domain statute, CC-BY, or licence-gated. Clients show this +// before the install button so an operator sees the terms they are +// taking on. +message DataSource { + // Publisher, as a person would name it. + string name = 1; + // Canonical URL of the upstream source. + string url = 2; + // Terms in plain words, not SPDX: the material often carries no + // software licence at all. + string license = 3; + // Attribution the operator must carry with the output. Empty when + // the upstream requires none. + string attribution = 4; + // True when a copy of the data ships inside the module bundle. + // Forbidden for `source.*` modules, allowed elsewhere only when + // `redistribution` says the publisher permits it, so a client can + // show the operator which of the two they are installing. + bool bundled = 5; + // What the publisher's terms say about passing the data on: + // `allowed`, `forbidden`, `unclear`, or empty when the question + // does not arise (nothing is bundled). + string redistribution = 6; +} + +message ChannelStatusResponse { + // Active channel pointer from `~/.chain/current-channel`. + string active = 1; + repeated ChannelEntry channels = 2; +} + +message ChannelEntry { + string name = 1; + uint32 port = 2; + // True iff a daemon is currently bound to that channel's port + // (PID file present + process alive). + bool running = 3; + // Endpoint string from `~/.chain/run/.endpoint` when + // the daemon is up, otherwise empty. + string endpoint = 4; +} + +message DaemonPathsResponse { + // Channel-scoped log file path (empty if Studio cannot + // resolve one — e.g. older daemon writes only to stderr). + string log_path = 1; + // SQLite audit-log database path. + string db_path = 2; + // Modules directory the registry scans. + string modules_dir = 3; + // Saved flows directory. + string flows_dir = 4; + // Operator config file (~/.chain/config.yaml). + string config_path = 5; + // PID file the daemon supervisor writes (for the active + // channel). + string pid_path = 6; +} + +message CheckUpdateResponse { + // The active channel ("dev", "beta", "production"). + string channel = 1; + // The version the running hub was built with. + string local_version = 2; + // The version the manifest advertises as latest. Empty if + // `manifest_reachable` is false. + string latest_version = 3; + // True iff `latest_version > local_version` (semver-aware). + bool update_available = 4; + // RFC 3339 timestamp of the release. Empty if not present. + string released_at = 5; + // URL of the release notes for `latest_version`. Empty if not + // present in the manifest. + string release_notes_url = 6; + // True iff the release host responded with a parseable manifest. + // False on network errors / 404 / malformed JSON. The remaining + // string fields are empty in that case; `reason` carries a + // human-readable diagnostic. + bool manifest_reachable = 7; + // Empty on success; carries an error description when + // `manifest_reachable=false`. + string reason = 8; + // Manifest URL that was queried (configurable per operator). + string manifest_url = 9; +} + +message SystemAiStatusResponse { + // True iff `system_llm` is configured AND privacy_mode != off. + bool enabled = 1; + // openai / anthropic / "" — empty when disabled. + string provider = 2; + // The endpoint URL the operator configured. Empty when disabled. + string endpoint = 3; + // Model identifier. Empty when disabled. + string model = 4; + // off / redacted / full — never empty. + string privacy_mode = 5; + // Name of the env var holding the API key (empty = no auth). + // Studio's settings page renders the *name*; never the value. + string api_key_env = 6; + // Number of cached System-AI explanations currently stored. + // Surfaced in Doctor + Settings so operators see the cache + // earning its keep. + uint64 cache_count = 7; +} + +message AskAiRequest { + // The prompt the operator wants answered. Studio assembles + // this client-side from the audit event being explained + // and the chosen privacy mode. + string prompt = 1; + // When true, skip the persistent cache and always hit the + // live provider. Studio's "Regenerate" button passes this so + // the operator can ask the model to think again. + bool force_fresh = 2; +} + +message AskAiResponse { + // Failure category, mapped from `system_llm::SystemLlmError`. + // Empty on success. Studio surfaces each value with a fix hint. + // Values: "" (success), "disabled", "env_missing", "network", + // "http", "parse", "empty_response". + string error_kind = 1; + // Human-readable diagnostic / answer. Always populated: + // either the assistant text on success, or the error detail + // on failure. + string text = 2; + // Round-trip latency in milliseconds (success only). For + // cache hits this is the *original* generation latency, not + // the cache-lookup time — the UI renders it as "originally + // took X" so the operator sees what a live call would cost. + uint32 latency_ms = 3; + // True iff the answer came from the persistent cache rather + // than a fresh provider round-trip. + bool cached = 4; + // ISO-8601 timestamp the cached entry was first generated. + // Empty for fresh answers. + string cached_at = 5; + // How many times this entry has been served from cache. + // 0 for fresh answers. + uint32 cache_hits = 6; +} + +message ClearSystemLlmCacheResponse { + // Number of cached entries that were dropped. + uint64 purged = 1; +} + +message UpdateSystemAiRequest { + // ollama / openai / lmstudio / vllm / custom (defaults to + // ollama if empty). + string provider = 1; + // Full URL up to and including /v1. Empty + privacy_mode!=off + // → returns InvalidArgument. + string endpoint = 2; + // Model identifier the provider expects. Empty + + // privacy_mode!=off → returns InvalidArgument. + string model = 3; + // Name of the env var holding the API key. Empty = no auth. + string api_key_env = 4; + // off / redacted / full. Empty defaults to "off". + string privacy_mode = 5; +} + +message TestSystemAiRequest { + // Draft system-AI config to probe with. Empty fields fall + // back to the live in-memory config — handy for "test current + // settings" without re-sending them. + string provider = 1; + string endpoint = 2; + string model = 3; + string api_key_env = 4; + string privacy_mode = 5; +} + +message ListSystemAiModelsResponse { + // Empty on success. Otherwise: same error-kind taxonomy as + // AskAi (network / http / parse / disabled / env_missing). + string error_kind = 1; + string text = 2; + repeated SystemAiModel models = 3; +} + +message SystemAiModel { + // Model identifier the operator passes as `model:`. + string id = 1; + // Optional family / owner string the provider returned. + string owned_by = 2; +} + +message PullSystemAiModelRequest { + // Draft endpoint + auth. Required; the model is the operator's + // pick. Currently only Ollama-style /api/pull is supported. + string endpoint = 1; + string api_key_env = 2; + // Model id to pull, e.g. `gemma3:4b`, `llama3.2:3b`. + string model = 3; +} + +message PullSystemAiModelResponse { + string error_kind = 1; + string text = 2; + // Total wall-clock time the pull took, in milliseconds. + uint32 elapsed_ms = 3; +} + +// One message in a PullSystemAiModelStream. +message PullProgressEvent { + oneof event { + // The pull moved on. + PullProgressUpdate update = 1; + // Terminal message, success or failure (see its error_kind). + PullSystemAiModelResponse finished = 2; + } +} + +// A single observation while a model downloads. +message PullProgressUpdate { + // The backend's own status text, e.g. "pulling manifest". Passed + // through verbatim rather than translated: it names layers and + // digests a client cannot reconstruct. + string status = 1; + // Bytes fetched so far for the layer this status refers to. + uint64 completed = 2; + // Size of that layer; zero for statuses that carry no size, which + // clients show as indeterminate rather than as zero progress. + uint64 total = 3; +} + +message HardwareInfoResponse { + // tiny / small / balanced / large / unknown — see + // docs/architecture/system-ai.md → "Hardware tiers". + string tier = 1; + // CPU brand string, e.g. "Apple M3 Pro". + string cpu_brand = 2; + uint32 cpu_cores = 3; + uint64 ram_mb = 4; + bool apple_silicon = 5; + bool dedicated_gpu = 6; + // Human-readable summary the editor renders verbatim, e.g. + // "Apple M3 Pro · 16 GB · balanced". + string summary = 7; +} + +message ListSystemAiCuratedModelsResponse { + repeated CuratedModel models = 1; + // ISO-date string from models.yaml (e.g. "2026-05-07"). Lets + // Studio show "curation last reviewed 3 weeks ago". + string last_reviewed = 2; +} + +message CuratedModel { + string id = 1; + string family = 2; + // Parameter count in billions. 0 for closed-source cloud + // models where we don't publish a number. + float params_b = 3; + // basic / good / excellent. + string quality_tier = 4; + // tiny / small / balanced / large. + string min_hw_tier = 5; + // Context window in K tokens (8 = 8192). + uint32 context_k = 6; + // Free-form note rendered as a tooltip in Studio. + string notes = 7; + // Licence identifier (gemma-license, apache-2.0, …). + string license = 8; +} + +message ClearEventLogRequest { + // Operator handle recorded in the chain.reset marker so the + // discontinuity is attributable. Required. + string reviewer = 1; + // Free-form reason recorded in the chain.reset marker. Required — + // dropping audit events without a reason is the kind of action + // operators are asked to defend later. + string reason = 2; +} + +message ClearEventLogResponse { + // Number of events that were purged (excludes the new + // chain.reset marker that seeds the fresh chain). + uint64 purged = 1; + // Channel the operation ran on, echoed back so the CLI can + // confirm which environment was affected. + string channel = 2; +} + +message SetDefaultScopeRequest { + // New `default_scope` value. The first entry is the + // primary scope (the resolver consults the others in order + // when the primary doesn't match). At least one entry is + // required; the hub returns InvalidArgument otherwise. + repeated string scope = 1; +} + +message DefaultScopeResponse { + // The current `default_scope` after the operation. + repeated string scope = 1; + // Catalog-known publisher segments the operator may pick + // from, sorted alphabetically. Surfaces a typeahead-friendly + // shortlist in the Studio editor; arbitrary entries are + // still allowed (operator may run a private publisher + // segment that isn't in the central catalog). + repeated string known_providers = 2; +} + +message ReloadAuthResponse { + // Number of tokens loaded into the live store after the + // swap. Operators sanity-check this against the number + // they expected to have in `auth.tokens:`. + uint32 token_count = 1; +} + +// Guided-setup answers, mirroring chain_core::guided_setup:: +// SetupAnswers (kebab-case wire values, e.g. "trying-out"). +// Unknown values are an INVALID_ARGUMENT — the enums live in Rust. +message PlanSetupRequest { + string scenario = 1; + string intent = 2; + string target = 3; + bool require_approval = 4; + bool data_must_stay_local = 5; + bool allow_unsigned_modules = 6; +} + +// The assembled SetupPlan — field-for-field what `chain init +// --answers … --plan-json` prints, so a GUI can render the same +// preview from either source. +message PlanSetupResponse { + string profile = 1; + repeated string modules = 2; + string starter_flow = 3; + string runbook = 4; + repeated string curated_docs = 5; + bool require_signatures = 6; + bool worm_audit = 7; + bool approval_step = 8; +} + +message AuthStatusResponse { + // Validator kind in the on-disk operator config: "static" or + // "jwt-rs256". + string validator = 1; + // True when the hub CURRENTLY accepts anonymous calls — computed + // from the live validator, not the on-disk config (the two differ + // until `ReloadAuth` picks up a config edit; see reload_required). + // Anonymous mode is the static validator with an empty + // `auth.tokens:` list — the local-dev default. + bool anonymous_allowed = 2; + // Static token entries; empty for the jwt-rs256 validator. + repeated AuthTokenInfo tokens = 3; + // jwt-rs256 parameters; unset for the static validator. + JwtValidatorInfo jwt = 4; + // True when the on-disk auth config (or the env vars it + // references) no longer produces the validator the hub is + // enforcing — the operator edited config.yaml or rotated a + // secret and still needs `ReloadAuth` (or a restart). Also true + // when the on-disk config is currently invalid. + bool reload_required = 5; +} + +message AuthTokenInfo { + // Operator-friendly name as it appears in audit-log lines. + string name = 1; + // Name of the environment variable holding the secret. The + // value itself never crosses the wire. + string token_env = 2; + // Whether that environment variable is currently set in the + // daemon's environment — the common rotation footgun. + bool env_set = 3; + // Scope grants, verbatim from config (coarse scopes like + // `read`/`execute`/`admin` and fine-grained T5 patterns like + // `execute:llm.*`). + repeated string scopes = 4; + // Requests-per-minute quota; 0 = unlimited. + uint32 rate_limit_per_minute = 5; +} + +message JwtValidatorInfo { + // Where the RSA public key comes from: "inline-pem" when the + // key is embedded in config, else the configured file path. + string key_source = 1; + // Required `aud` claim; empty = not checked. + string audience = 2; + // Required `iss` claim; empty = not checked. + string issuer = 3; + // Claim carrying the caller's scopes. + string scope_claim = 4; +} + +message McpClientConfigEntry { + // Operator-friendly name. Becomes the second segment of + // every discovered capability id: `mcp..`. + // Must be unique and not contain dots. + string name = 1; + // Endpoint URL. HTTP(S) for streamable-HTTP servers, + // `stdio://` for local stdio servers. + string endpoint = 2; + // Optional env-var name holding a bearer token. + string api_key_env = 3; + // Optional human-readable description. + string description = 4; +} + +message ListMcpClientsResponse { + // Every configured server (regardless of last-discovery + // outcome). + repeated McpClientStatus clients = 1; +} + +message McpClientStatus { + McpClientConfigEntry config = 1; + // Number of tools the last discovery pass returned. 0 + // before discovery has run or on failure. + uint32 tool_count = 2; + // Empty on success; otherwise the error_kind taxonomy + // (`invalid_endpoint`, `not_implemented`, `network`, + // `http`, `server`, `parse`, `env_missing`). + string error_kind = 3; + // Human-readable diagnostic. On success "registered N + // tools"; on failure the error message. + string message = 4; +} + +message RemoveMcpClientRequest { + string name = 1; +} + +message N8nEndpointConfigEntry { + string name = 1; + // Base URL without the /api/v1 suffix. + string base_url = 2; + string api_key_env = 3; + string description = 4; +} + +message ListN8nEndpointsResponse { + repeated N8nEndpointStatus endpoints = 1; +} + +message N8nEndpointStatus { + N8nEndpointConfigEntry config = 1; + uint32 workflow_count = 2; + string error_kind = 3; + string message = 4; +} + +message RemoveN8nEndpointRequest { + string name = 1; +} + +message IssueBootstrapTokenRequest { + // Operator-friendly satellite display name the token enrols. + string satellite_name = 1; + // Optional region tag signed into the issued cert at enrollment. + string region = 2; + // Token lifetime in seconds; 0 defaults to 24h server-side. + uint64 ttl_seconds = 3; +} + +message IssueBootstrapTokenResponse { + // The single-use token. Shown once; hand it to the satellite + // operator over a secure channel. + string token = 1; + // ISO-8601 expiry of the token. + string expires_at = 2; + // The primary's CA certificate PEM. The operator installs this on + // the satellite (`federation.primary_ca`) alongside the token so + // the satellite verifies the primary on its very first connect — + // closing the first-connect MITM window with no extra lookup. + string primary_ca_pem = 3; +} + +message SatelliteList { + repeated SatelliteEntry satellites = 1; +} + +message SatelliteEntry { + // Immutable hub UUID of the satellite. + string hub_id = 1; + // Operator-chosen display name. + string display_name = 2; + // Ch∆In version the satellite reported. + string hub_version = 3; + // Negotiated federation wire version. + uint32 wire_version = 4; + // Region tag, empty when none. + string region = 5; + // Capability ids the satellite currently advertises. + repeated string capabilities = 6; +} + +// ---- Store management (Studio store manager) ---- + +message ListStoresRequest {} + +message StoreSource { + // "bundled" for the seed index, else the operator-given name. + string name = 1; + // Index URL; empty for the bundled seed. + string url = 2; + // False for the bundled seed (cannot be removed). + bool removable = 3; + // Modules currently contributed by this source to the live index. + int32 module_count = 4; + // True when this store pins a cosign publisher key + // (`trust.public_key_pem`, or the built-in official key for the + // bundled seed) — installs from it are verified against that key + // whenever signature checking is on. + bool key_pinned = 5; +} + +message ListStoresResponse { + repeated StoreSource stores = 1; + // Operator policy snapshot so store UIs can say honestly whether + // installs are signature-checked at all. + bool require_signatures = 2; + // Number of globally trusted publisher identities + // (`security.trusted_publishers`). + int32 trusted_publisher_count = 3; +} + +message AddStoreRequest { + // Operator-friendly name, unique within configured stores. + string name = 1; + // Index URL: https:// , http:// , or file:// . + string url = 2; + // Optional bearer-token env var name (hub reads $value at request time). + string bearer_env = 3; + // Optional HTTP Basic username. + string basic_user = 4; + // Optional HTTP Basic password env var name. Pair with basic_user. + string basic_password_env = 5; + // Optional PEM PUBLIC key to pin for this store (cosign key-pinning). + // When set, signed modules from this store verify against THIS + // publisher key instead of the global/built-in vendor anchor, so a + // domain publisher signs with its own key without the vendor master. + string pinned_pubkey_pem = 6; +} + +message AddStoreResponse { + // Modules the new store contributed to the live index. + int32 modules_added = 1; + // Human-readable result (e.g. "added 8 modules from reclaim"). + string message = 2; +} + +message RemoveStoreRequest { + string name = 1; +} + +message RemoveStoreResponse { + bool removed = 1; + string message = 2; +} diff --git a/proto/chain/v1/module.proto b/proto/chain/v1/module.proto new file mode 100644 index 0000000..bbd35c5 --- /dev/null +++ b/proto/chain/v1/module.proto @@ -0,0 +1,45 @@ +syntax = "proto3"; + +package chain.v1; + +import "google/protobuf/empty.proto"; +import "chain/v1/common.proto"; + +// The Module service is what the hub calls to invoke a module. +// +// In Phase 0, modules run in-process as WASM components and this +// service is not over the wire. The proto definition exists so that +// external module processes (OCI, remote) can implement the same +// contract in Phase 1+. +service Module { + // Invoke the module once with typed inputs, receive typed outputs. + rpc Invoke(InvokeRequest) returns (InvokeResponse); + + // Return the module's self-description. + rpc Describe(google.protobuf.Empty) returns (ModuleDescriptor); +} + +message InvokeRequest { + InvocationId invocation_id = 1; + CapabilityRef capability = 2; + map inputs = 3; + uint64 deadline_ms = 4; +} + +message InvokeResponse { + oneof result { + Success success = 1; + ChainError error = 2; + } +} + +message Success { + map outputs = 1; +} + +message ModuleDescriptor { + string name = 1; + string version = 2; + repeated CapabilityRef provides = 3; + repeated string permissions = 4; +} diff --git a/scripts/sync-proto.mjs b/scripts/sync-proto.mjs new file mode 100644 index 0000000..4fc905e --- /dev/null +++ b/scripts/sync-proto.mjs @@ -0,0 +1,40 @@ +#!/usr/bin/env node +// Refresh the verbatim `chain.v1` copies from the platform repo and +// record their hashes. +// +// Usage: node scripts/sync-proto.mjs [path-to-platform-repo] +// Default: ../fai_chain, or $CHAIN_PLATFORM_REPO. + +import { createHash } from 'node:crypto'; +import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'; +import { dirname, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const here = dirname(fileURLToPath(import.meta.url)); +const root = resolve(here, '..'); +const files = [ + 'chain/v1/common.proto', + 'chain/v1/hub.proto', + 'chain/v1/module.proto', + 'chain/v1/federation.proto', +]; + +const platform = resolve( + process.argv[2] ?? process.env.CHAIN_PLATFORM_REPO ?? join(root, '..', 'fai_chain'), +); +if (!existsSync(join(platform, 'proto', 'chain', 'v1', 'hub.proto'))) { + console.error(`no proto/chain/v1 under ${platform}`); + process.exit(1); +} + +const lines = []; +for (const file of files) { + const from = join(platform, 'proto', file); + const to = join(root, 'proto', file); + copyFileSync(from, to); + const hash = createHash('sha256').update(readFileSync(to)).digest('hex'); + lines.push(`${hash} ${file}`); + console.log(`${file} <- ${from}`); +} +writeFileSync(join(root, 'proto', 'CHECKSUMS'), `${lines.join('\n')}\n`, 'utf8'); +console.log('proto/CHECKSUMS written'); diff --git a/src/client.ts b/src/client.ts new file mode 100644 index 0000000..ed2898d --- /dev/null +++ b/src/client.ts @@ -0,0 +1,478 @@ +// The hub client. +// +// One method per thing a portal backend does: start a flow, follow +// it, ask what became of it, decide an approval. Everything the +// Ch∆In hub can do beyond that is reachable over the raw proto +// surface (see `chainProto`), which this file does not try to mirror. + +import * as grpc from '@grpc/grpc-js'; + +import { ChainError, asKind, chainErrorFrom, stepFromMessage } from './errors.js'; +import { + type PayloadInput, + type PayloadOutput, + type WirePayload, + payloadFromWire, + payloadToWire, +} from './payload.js'; +import { hubAdminServiceConstructor, hubServiceConstructor } from './proto.js'; + +/** Client certificates and roots, for a hub behind mTLS. */ +export interface TlsOptions { + /** PEM of the CA that signed the hub's certificate. */ + rootCerts?: Buffer; + /** PEM of this client's private key (mTLS). */ + privateKey?: Buffer; + /** PEM of this client's certificate chain (mTLS). */ + certChain?: Buffer; +} + +/** How to reach the hub. */ +export interface ChainClientOptions { + /** `host:port`, e.g. `127.0.0.1:50051`. */ + address: string; + /** Bearer token, when the hub requires one. */ + token?: string; + /** TLS. `true` uses the system roots; an object pins roots or adds a client certificate. */ + tls?: TlsOptions | true; + /** Project every call belongs to unless a call overrides it. */ + project?: string; + /** Deadline for a single call, in milliseconds. Default 30000. */ + deadlineMs?: number; + /** Passed through to grpc-js, e.g. message size limits. */ + channelOptions?: grpc.ChannelOptions; +} + +/** Starting a flow. */ +export interface SubmitOptions { + /** The flow definition as YAML. */ + flowYaml: string; + /** Named flow inputs. */ + inputs?: Record; + /** Project this run belongs to; defaults to the client's. */ + project?: string; + /** + * Return as soon as the run has an id and keep it running in the + * background. Follow it with `getStatus` / `getResult`. + */ + detach?: boolean; + /** + * The caller's key for "this is the same request as before". A + * second submit with a key the hub has already seen returns the + * first run instead of starting a second one. Needed wherever the + * caller may retry, for example a payment webhook. + */ + idempotencyKey?: string; + /** Deadline for this call; defaults to the client's. */ + deadlineMs?: number; +} + +/** What a finished run produced. */ +export interface FlowResult { + /** The hub's id for this run. */ + invocationId: string; + /** The flow's declared outputs. */ + outputs: Record; +} + +/** Where a detached run stands. */ +export interface InvocationStatus { + phase: 'PENDING' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED' | 'PHASE_UNKNOWN'; + /** Step currently executing, empty unless running. */ + currentStep: string; + startedAt: string; + finishedAt: string; + /** Error message when the phase is FAILED. */ + error: string; +} + +/** One thing that happened while a flow ran. */ +export type FlowEvent = + | { type: 'stepStarted'; step: string; capability: string } + | { type: 'stepFinished'; step: string; ok: boolean; durationMs: number } + | { type: 'moduleEvent'; step: string; name: string; payload: PayloadOutput } + | { type: 'result'; result: FlowResult }; + +/** A step waiting for a human decision. */ +export interface Approval { + approvalId: string; + flowExecution: string; + flowName: string; + stepId: string; + /** What the reviewer is being asked, written by the flow. */ + prompt: string; + payloadPreview: string; + createdAt: string; + expiresAt: string; + status: string; + decidedAt: string; + decidedBy: string; + reason: string; + project: string; +} + +/** Deciding an approval. */ +export interface DecideApprovalOptions { + approvalId: string; + /** True approves, false rejects. */ + approve: boolean; + /** + * Who decided. The hub overrides this with the identity behind the + * token when it can verify one, so this is a fallback, not a claim + * the hub trusts blindly. + */ + reviewer?: string; + /** Why. Required when rejecting. */ + reason?: string; + deadlineMs?: number; +} + +/** Health of the hub. */ +export interface HubHealth { + state: 'SERVING' | 'NOT_SERVING' | 'UNKNOWN'; + detail: string; +} + +interface WireSubmitResponse { + invocationId?: { value?: string }; + outputs?: Record; +} + +type UnaryCallback = (err: grpc.ServiceError | null, res?: T) => void; + +const DEFAULT_DEADLINE_MS = 30_000; + +/** A connection to one hub. */ +export class ChainClient { + private readonly hub: grpc.Client; + private readonly admin: grpc.Client; + private readonly token: string | undefined; + private readonly project: string; + private readonly deadlineMs: number; + + constructor(options: ChainClientOptions) { + const credentials = options.tls + ? grpc.credentials.createSsl( + options.tls === true ? undefined : options.tls.rootCerts, + options.tls === true ? undefined : options.tls.privateKey, + options.tls === true ? undefined : options.tls.certChain, + ) + : grpc.credentials.createInsecure(); + const channelOptions = options.channelOptions ?? {}; + const Hub = hubServiceConstructor(); + const HubAdmin = hubAdminServiceConstructor(); + this.hub = new Hub(options.address, credentials, channelOptions); + this.admin = new HubAdmin(options.address, credentials, channelOptions); + this.token = options.token; + this.project = options.project ?? ''; + this.deadlineMs = options.deadlineMs ?? DEFAULT_DEADLINE_MS; + } + + /** Close both channels. Pending calls fail with `cancelled`. */ + close(): void { + this.hub.close(); + this.admin.close(); + } + + private metadata(): grpc.Metadata { + const md = new grpc.Metadata(); + if (this.token) md.set('authorization', `Bearer ${this.token}`); + return md; + } + + private options(deadlineMs?: number): grpc.CallOptions { + return { deadline: Date.now() + (deadlineMs ?? this.deadlineMs) }; + } + + private unary( + client: grpc.Client, + method: string, + request: Req, + deadlineMs?: number, + ): Promise { + return new Promise((resolve, reject) => { + const fn = (client as unknown as Record)[method]; + if (typeof fn !== 'function') { + reject(new Error(`grpc method ${method} not found on the client`)); + return; + } + const callback: UnaryCallback = (err, res) => { + if (err) { + reject(chainErrorFrom(err)); + return; + } + resolve((res ?? {}) as Res); + }; + (fn as (...args: unknown[]) => unknown).call( + client, + request, + this.metadata(), + this.options(deadlineMs), + callback, + ); + }); + } + + /** Is the hub serving? */ + async health(deadlineMs?: number): Promise { + const res = await this.unary, { state?: string; detail?: string }>( + this.hub, + 'health', + {}, + deadlineMs, + ); + const state = res.state === 'SERVING' || res.state === 'NOT_SERVING' ? res.state : 'UNKNOWN'; + return { state, detail: res.detail ?? '' }; + } + + private submitRequest(options: SubmitOptions): Record { + const inputs: Record = {}; + for (const [name, value] of Object.entries(options.inputs ?? {})) { + inputs[name] = payloadToWire(value); + } + return { + flowYaml: Buffer.from(options.flowYaml, 'utf8'), + inputs, + detach: options.detach ?? false, + project: options.project ?? this.project, + idempotencyKey: options.idempotencyKey ?? '', + }; + } + + private static resultFrom(res: WireSubmitResponse): FlowResult { + const outputs: Record = {}; + for (const [name, payload] of Object.entries(res.outputs ?? {})) { + outputs[name] = payloadFromWire(payload); + } + return { invocationId: res.invocationId?.value ?? '', outputs }; + } + + /** + * Run a flow and wait for it. + * + * With `detach: true` it returns once the run has an id; the + * outputs are then empty and `getResult` fetches them later. + */ + async submit(options: SubmitOptions): Promise { + const res = await this.unary, WireSubmitResponse>( + this.hub, + 'submit', + this.submitRequest(options), + options.deadlineMs, + ); + return ChainClient.resultFrom(res); + } + + /** + * Run a flow and follow it step by step. + * + * The iterator ends after the `result` event. A run that fails + * throws a `ChainError` carrying the hub's error class, so the + * events seen so far stay valid and the failure is not a silent + * end of stream. + */ + async *submitStream(options: SubmitOptions): AsyncGenerator { + const fn = (this.hub as unknown as Record).submitStream; + if (typeof fn !== 'function') throw new Error('grpc method submitStream not found'); + const call = (fn as (...args: unknown[]) => grpc.ClientReadableStream).call( + this.hub, + this.submitRequest(options), + this.metadata(), + this.options(options.deadlineMs), + ); + + const queue: FlowEvent[] = []; + let failure: unknown; + let done = false; + let wake: (() => void) | undefined; + const signal = () => { + const w = wake; + wake = undefined; + w?.(); + }; + + call.on('data', (event: Record) => { + const translated = translateStreamEvent(event); + if (translated instanceof ChainError) { + failure = translated; + done = true; + } else if (translated) { + queue.push(translated); + } + signal(); + }); + call.on('error', (err: unknown) => { + failure = chainErrorFrom(err); + done = true; + signal(); + }); + call.on('end', () => { + done = true; + signal(); + }); + + try { + for (;;) { + while (queue.length > 0) { + yield queue.shift() as FlowEvent; + } + if (failure) throw failure; + if (done) return; + await new Promise((resolve) => { + wake = resolve; + }); + } + } finally { + call.cancel(); + } + } + + /** Where a detached run stands. */ + async getStatus(invocationId: string, deadlineMs?: number): Promise { + const res = await this.unary< + { value: string }, + Partial & { phase?: string } + >(this.hub, 'getInvocationStatus', { value: invocationId }, deadlineMs); + return { + phase: (res.phase as InvocationStatus['phase']) ?? 'PHASE_UNKNOWN', + currentStep: res.currentStep ?? '', + startedAt: res.startedAt ?? '', + finishedAt: res.finishedAt ?? '', + error: res.error ?? '', + }; + } + + /** The outputs of a finished detached run. */ + async getResult(invocationId: string, deadlineMs?: number): Promise { + const res = await this.unary<{ value: string }, WireSubmitResponse>( + this.hub, + 'getInvocationResult', + { value: invocationId }, + deadlineMs, + ); + return ChainClient.resultFrom(res); + } + + /** Stop a detached run. Returns false when it was already over. */ + async cancel(invocationId: string, deadlineMs?: number): Promise { + const res = await this.unary<{ value: string }, { cancelled?: boolean }>( + this.hub, + 'cancelInvocation', + { value: invocationId }, + deadlineMs, + ); + return res.cancelled ?? false; + } + + /** Steps waiting for a decision. */ + async listApprovals( + options: { statuses?: string[]; limit?: number; project?: string; deadlineMs?: number } = {}, + ): Promise { + const res = await this.unary< + { statuses: string[]; limit: number; project: string }, + { entries?: Partial[] } + >( + this.admin, + 'listApprovals', + { + statuses: options.statuses ?? ['PENDING'], + limit: options.limit ?? 100, + project: options.project ?? this.project, + }, + options.deadlineMs, + ); + return (res.entries ?? []).map((e) => ({ + approvalId: e.approvalId ?? '', + flowExecution: e.flowExecution ?? '', + flowName: e.flowName ?? '', + stepId: e.stepId ?? '', + prompt: e.prompt ?? '', + payloadPreview: e.payloadPreview ?? '', + createdAt: e.createdAt ?? '', + expiresAt: e.expiresAt ?? '', + status: e.status ?? '', + decidedAt: e.decidedAt ?? '', + decidedBy: e.decidedBy ?? '', + reason: e.reason ?? '', + project: e.project ?? '', + })); + } + + /** Approve or reject a waiting step. */ + async decideApproval( + options: DecideApprovalOptions, + ): Promise<{ approvalId: string; status: string }> { + const res = await this.unary, { approvalId?: string; status?: string }>( + this.admin, + 'decideApproval', + { + approvalId: options.approvalId, + decision: options.approve ? 'APPROVE' : 'REJECT', + reviewer: options.reviewer ?? '', + reason: options.reason ?? '', + }, + options.deadlineMs, + ); + return { approvalId: res.approvalId ?? options.approvalId, status: res.status ?? '' }; + } +} + +/** + * Translate one `SubmitStreamEvent`. A `StreamError` comes back as a + * `ChainError` for the caller to throw; anything unknown (a newer + * hub) comes back as `undefined` and is skipped. + */ +function translateStreamEvent(event: Record): FlowEvent | ChainError | undefined { + const started = event.stepStarted as { step?: string; capability?: string } | undefined; + if (started) { + return { type: 'stepStarted', step: started.step ?? '', capability: started.capability ?? '' }; + } + const finished = event.stepFinished as + | { step?: string; ok?: boolean; durationMs?: number } + | undefined; + if (finished) { + return { + type: 'stepFinished', + step: finished.step ?? '', + ok: finished.ok ?? false, + durationMs: Number(finished.durationMs ?? 0), + }; + } + const moduleEvent = event.moduleEvent as + | { step?: string; name?: string; payload?: WirePayload } + | undefined; + if (moduleEvent) { + return { + type: 'moduleEvent', + step: moduleEvent.step ?? '', + name: moduleEvent.name ?? '', + payload: payloadFromWire(moduleEvent.payload), + }; + } + const final = event.finalResult as WireSubmitResponse | undefined; + if (final) { + const outputs: Record = {}; + for (const [name, payload] of Object.entries(final.outputs ?? {})) { + outputs[name] = payloadFromWire(payload); + } + return { + type: 'result', + result: { invocationId: final.invocationId?.value ?? '', outputs }, + }; + } + const error = event.error as { message?: string; kind?: string } | undefined; + if (error) { + // The hub answered, so `reachedHub` is true whether or not this + // hub is new enough to name the class. Without a class the error + // reads as `internal` rather than claiming one it does not know. + const kind = error.kind ? asKind(error.kind) : 'internal'; + const message = error.message ?? 'the run failed'; + return new ChainError(message, { + kind, + code: grpc.status.UNKNOWN, + reachedHub: true, + step: stepFromMessage(message), + }); + } + return undefined; +} diff --git a/src/errors.ts b/src/errors.ts new file mode 100644 index 0000000..7a4e491 --- /dev/null +++ b/src/errors.ts @@ -0,0 +1,234 @@ +// Error classification for hub calls. +// +// Two facts are kept apart on purpose: +// +// * `kind` is the hub's own word for what went wrong. It travels in +// the `chain-error-kind` trailer of every error response. +// * `reachedHub` says whether the hub answered at all. A refused TCP +// connection and a hub that answers "the model host is down" both +// arrive as gRPC UNAVAILABLE; a gateway that shows "service not +// reachable" for the second one is lying to its users. +// +// Callers that only want a coarse branch use `family`. + +import { status as GrpcStatus } from '@grpc/grpc-js'; +import type { ServiceError } from '@grpc/grpc-js'; + +/** Metadata key under which the hub sends the error class. */ +export const ERROR_KIND_KEY = 'chain-error-kind'; + +/** + * The hub's error classes. The vocabulary grows additively; an + * unknown word from a newer hub shows up as `'unknown'`, never as a + * crash. + */ +export type ChainErrorKind = + | 'flow_rejected' + | 'step_failed' + | 'step_timeout' + | 'approval_rejected' + | 'approval_timeout' + | 'unavailable' + | 'overloaded' + | 'precondition' + | 'not_found' + | 'conflict' + | 'forbidden' + | 'unauthenticated' + | 'timeout' + | 'cancelled' + | 'internal' + | 'unknown'; + +/** Coarse branch for callers that do not care about the detail. */ +export type ChainErrorFamily = + | 'unreachable' + | 'rejected' + | 'failed' + | 'overloaded' + | 'auth' + | 'timeout' + | 'cancelled' + | 'internal'; + +const KNOWN_KINDS: ReadonlySet = new Set([ + 'flow_rejected', + 'step_failed', + 'step_timeout', + 'approval_rejected', + 'approval_timeout', + 'unavailable', + 'overloaded', + 'precondition', + 'not_found', + 'conflict', + 'forbidden', + 'unauthenticated', + 'timeout', + 'cancelled', + 'internal', +]); + +const FAMILY_OF: Record = { + flow_rejected: 'rejected', + not_found: 'rejected', + conflict: 'rejected', + precondition: 'rejected', + step_failed: 'failed', + step_timeout: 'failed', + approval_rejected: 'failed', + approval_timeout: 'failed', + unavailable: 'unreachable', + overloaded: 'overloaded', + forbidden: 'auth', + unauthenticated: 'auth', + timeout: 'timeout', + cancelled: 'cancelled', + internal: 'internal', + unknown: 'internal', +}; + +const RETRYABLE: ReadonlySet = new Set([ + 'unreachable', + 'overloaded', + 'timeout', +]); + +/** Map a gRPC code to a class, for a hub that sent no class. */ +export function kindForCode(code: number): ChainErrorKind { + switch (code) { + case GrpcStatus.INVALID_ARGUMENT: + case GrpcStatus.OUT_OF_RANGE: + return 'flow_rejected'; + case GrpcStatus.NOT_FOUND: + return 'not_found'; + case GrpcStatus.ALREADY_EXISTS: + case GrpcStatus.ABORTED: + return 'conflict'; + case GrpcStatus.FAILED_PRECONDITION: + return 'precondition'; + case GrpcStatus.UNAVAILABLE: + return 'unavailable'; + case GrpcStatus.RESOURCE_EXHAUSTED: + return 'overloaded'; + case GrpcStatus.DEADLINE_EXCEEDED: + return 'timeout'; + case GrpcStatus.PERMISSION_DENIED: + return 'forbidden'; + case GrpcStatus.UNAUTHENTICATED: + return 'unauthenticated'; + case GrpcStatus.CANCELLED: + return 'cancelled'; + case GrpcStatus.INTERNAL: + case GrpcStatus.DATA_LOSS: + case GrpcStatus.UNIMPLEMENTED: + case GrpcStatus.UNKNOWN: + return 'internal'; + default: + return 'unknown'; + } +} + +/** Fields that `ChainError` carries beyond the message. */ +export interface ChainErrorInit { + kind: ChainErrorKind; + /** Numeric gRPC code, 2 (UNKNOWN) when the failure never got one. */ + code: number; + /** True when the hub answered; false for a failure to reach it. */ + reachedHub: boolean; + /** Flow step the hub blamed, when it named one. */ + step?: string; + /** Invocation the failure belongs to, when one exists. */ + invocationId?: string; + cause?: unknown; +} + +/** Every failure this client raises. */ +export class ChainError extends Error { + readonly kind: ChainErrorKind; + readonly family: ChainErrorFamily; + readonly code: number; + readonly reachedHub: boolean; + readonly retryable: boolean; + readonly step: string | undefined; + readonly invocationId: string | undefined; + + constructor(message: string, init: ChainErrorInit) { + super(message, init.cause === undefined ? undefined : { cause: init.cause }); + this.name = 'ChainError'; + this.kind = init.kind; + this.family = FAMILY_OF[init.kind]; + this.code = init.code; + this.reachedHub = init.reachedHub; + this.retryable = RETRYABLE.has(this.family); + this.step = init.step; + this.invocationId = init.invocationId; + } + + /** One line that is safe to log: no inputs, no payloads. */ + override toString(): string { + const where = this.step ? ` step=${this.step}` : ''; + return `ChainError[${this.kind}/${this.family}] ${this.message}${where}`; + } +} + +/** A word from the hub, as a class this version knows. */ +export function asKind(word: string): ChainErrorKind { + return KNOWN_KINDS.has(word) ? (word as ChainErrorKind) : 'unknown'; +} + +function kindFromMetadata(err: ServiceError): ChainErrorKind | undefined { + const raw = err.metadata?.get(ERROR_KIND_KEY)?.[0]; + if (raw === undefined) return undefined; + const word = typeof raw === 'string' ? raw : raw.toString('utf8'); + return asKind(word); +} + +/** + * Turn a grpc-js service error into a `ChainError`. + * + * The hub's own class wins. Without one, the gRPC code decides, and + * the absence of the trailer is what tells us the hub never answered: + * grpc-js produces UNAVAILABLE for a refused connection, and the hub + * produces UNAVAILABLE for a dependency that is down. Only the second + * one carries a class. + */ +export function chainErrorFrom(err: unknown, context?: { invocationId?: string }): ChainError { + if (err instanceof ChainError) return err; + const svc = err as ServiceError; + const code = typeof svc?.code === 'number' ? svc.code : GrpcStatus.UNKNOWN; + const fromHub = svc?.metadata ? kindFromMetadata(svc) : undefined; + // A CANCELLED status without a class did not come from the hub: the + // transport dropped the call, which happens when the hub goes down + // mid-request. Reading it as "cancelled" would tell a gateway that + // it cancelled its own run. This client never cancels a unary call, + // so the only cancellation it can see is a lost connection. + const kind = + fromHub ?? + (code === GrpcStatus.CANCELLED ? 'unavailable' : kindForCode(code)); + const message = typeof svc?.details === 'string' && svc.details.length > 0 + ? svc.details + : (svc?.message ?? 'hub call failed'); + return new ChainError(message, { + kind, + code, + reachedHub: fromHub !== undefined, + step: stepFromMessage(message), + invocationId: context?.invocationId, + cause: err, + }); +} + +/** + * Pull the step id out of a hub message when it names one. + * + * Exported because a stream error carries the same prose. + * + * The hub's prose starts with `step ''` for step-level failures. + * This is a convenience for logs and nothing branches on it, so a + * wording change costs a `undefined`, not a wrong decision. + */ +export function stepFromMessage(message: string): string | undefined { + const m = /step '([^']+)'/.exec(message); + return m?.[1]; +} diff --git a/src/fake_hub.ts b/src/fake_hub.ts new file mode 100644 index 0000000..234f8f7 --- /dev/null +++ b/src/fake_hub.ts @@ -0,0 +1,668 @@ +// A hub that answers like the real one, including when it says no. +// +// Point of this file: a gateway's tests must not need a real hub, a +// real module or a real model. The fake speaks the same `chain.v1` +// service from the same `.proto` files, so a test exercises the +// client's own encoding and error classification, not a mock of it. +// +// What can be scripted: a run that succeeds, a run that fails with +// any error class, an overloaded hub, a hub that is not listening at +// all, a run that waits for an approval, and a restart that loses the +// waiting run while keeping the approval, which is what today's hub +// really does (see HANDOVER: run state is in memory, approvals are in +// SQLite). + +import * as grpc from '@grpc/grpc-js'; + +import type { ChainErrorKind } from './errors.js'; +import { type PayloadInput, type PayloadOutput, type WirePayload, payloadFromWire, payloadToWire } from './payload.js'; +import { hubAdminServiceDefinition, hubServiceDefinition } from './proto.js'; + +/** gRPC codes the fake uses for each class, mirroring the hub. */ +const CODE_FOR_KIND: Record = { + flow_rejected: grpc.status.INVALID_ARGUMENT, + step_failed: grpc.status.INVALID_ARGUMENT, + step_timeout: grpc.status.DEADLINE_EXCEEDED, + approval_rejected: grpc.status.PERMISSION_DENIED, + approval_timeout: grpc.status.DEADLINE_EXCEEDED, + unavailable: grpc.status.UNAVAILABLE, + overloaded: grpc.status.RESOURCE_EXHAUSTED, + precondition: grpc.status.FAILED_PRECONDITION, + not_found: grpc.status.NOT_FOUND, + conflict: grpc.status.ALREADY_EXISTS, + forbidden: grpc.status.PERMISSION_DENIED, + unauthenticated: grpc.status.UNAUTHENTICATED, + timeout: grpc.status.DEADLINE_EXCEEDED, + cancelled: grpc.status.CANCELLED, + internal: grpc.status.INTERNAL, +}; + +/** A run that finishes. */ +export interface SucceedBehaviour { + type: 'succeed'; + /** Flow outputs, in the same shapes a caller passes as inputs. */ + outputs?: Record; + /** Steps to report while streaming. */ + steps?: string[]; +} + +/** A run, or a request, that fails. */ +export interface FailBehaviour { + type: 'fail'; + kind: ChainErrorKind; + message: string; +} + +/** A run that stops at an approval and waits for a decision. */ +export interface AwaitApprovalBehaviour { + type: 'awaitApproval'; + /** What the reviewer is asked. */ + prompt: string; + /** Step id of the approval, for the approval row and the status. */ + stepId?: string; + /** Outputs once it is approved. */ + outputs?: Record; + /** Steps to report before the approval while streaming. */ + steps?: string[]; +} + +/** One scripted answer. */ +export type Behaviour = SucceedBehaviour | FailBehaviour | AwaitApprovalBehaviour; + +/** A submit the fake received. */ +export interface RecordedSubmit { + flowYaml: string; + inputs: Record; + project: string; + detach: boolean; + idempotencyKey: string; + invocationId: string; +} + +/** A decision the fake received. */ +export interface RecordedDecision { + approvalId: string; + decision: string; + reviewer: string; + reason: string; +} + +interface PendingApproval { + approvalId: string; + flowExecution: string; + flowName: string; + stepId: string; + prompt: string; + createdAt: string; + status: 'PENDING' | 'APPROVED' | 'REJECTED'; + decidedAt: string; + decidedBy: string; + reason: string; + project: string; +} + +interface Waiter { + approvalId: string; + invocationId: string; + outputs: Record; + settle: (outcome: { ok: true; outputs: Record } | { ok: false; kind: ChainErrorKind; message: string }) => void; +} + +interface RunState { + phase: 'PENDING' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED'; + currentStep: string; + startedAt: string; + finishedAt: string; + error: string; + outputs: Record; +} + +function nowIso(): string { + return new Date().toISOString(); +} + +let counter = 0; +function nextId(prefix: string): string { + counter += 1; + return `${prefix}-${counter}`; +} + +function errorFor(kind: ChainErrorKind, message: string): grpc.ServiceError { + const metadata = new grpc.Metadata(); + metadata.set('chain-error-kind', kind); + const code = CODE_FOR_KIND[kind] ?? grpc.status.UNKNOWN; + const err = new Error(message) as grpc.ServiceError; + err.code = code; + err.details = message; + err.metadata = metadata; + return err; +} + +function wireOutputs(outputs: Record): Record { + const out: Record = {}; + for (const [name, value] of Object.entries(outputs)) { + out[name] = payloadToWire(value); + } + return out; +} + +/** A scriptable stand-in for a hub. */ +export class FakeHub { + private server: grpc.Server | undefined; + private port = 0; + + /** Answers for the next submits, in order. */ + private readonly script: Behaviour[] = []; + + /** Answer used once the script is empty. */ + private fallback: Behaviour = { type: 'succeed', outputs: {} }; + + private health: 'SERVING' | 'NOT_SERVING' = 'SERVING'; + + /** Everything the fake was asked to run. */ + readonly submits: RecordedSubmit[] = []; + + /** Every decision the fake was handed. */ + readonly decisions: RecordedDecision[] = []; + + /** + * Approvals. Kept across `restart()`, because the real hub keeps + * them in SQLite. + */ + private approvals: PendingApproval[] = []; + + /** Runs. Dropped by `restart()`, like the real hub drops them. */ + private runs = new Map(); + + /** Submits blocked on an approval. Dropped by `restart()`. */ + private waiters = new Map(); + + /** Idempotency keys this fake has seen, per project. */ + private keys = new Map(); + + /** Script the next submit. */ + push(behaviour: Behaviour): this { + this.script.push(behaviour); + return this; + } + + /** The next submit succeeds with these outputs. */ + succeeds(outputs: Record = {}, steps?: string[]): this { + return this.push(steps ? { type: 'succeed', outputs, steps } : { type: 'succeed', outputs }); + } + + /** The next submit fails with this class. */ + fails(kind: ChainErrorKind, message = 'scripted failure'): this { + return this.push({ type: 'fail', kind, message }); + } + + /** The next submit waits for an approval. */ + waitsForApproval(options: Omit): this { + return this.push({ type: 'awaitApproval', ...options }); + } + + /** Answer every further submit this way. */ + setFallback(behaviour: Behaviour): this { + this.fallback = behaviour; + return this; + } + + /** Report NOT_SERVING on Health while staying reachable. */ + setHealth(state: 'SERVING' | 'NOT_SERVING'): this { + this.health = state; + return this; + } + + /** The approvals the fake currently holds. */ + pendingApprovals(): PendingApproval[] { + return this.approvals.filter((a) => a.status === 'PENDING'); + } + + /** `host:port` of the running fake. */ + get address(): string { + if (!this.port) throw new Error('fake hub is not listening'); + return `127.0.0.1:${this.port}`; + } + + /** Start listening. Keeps the port across a `restart()`. */ + async start(port = 0): Promise { + if (this.server) throw new Error('fake hub is already listening'); + const server = new grpc.Server(); + server.addService(hubServiceDefinition(), this.hubHandlers()); + server.addService(hubAdminServiceDefinition(), this.adminHandlers()); + const bound = await new Promise((resolve, reject) => { + server.bindAsync( + `127.0.0.1:${port || this.port || 0}`, + grpc.ServerCredentials.createInsecure(), + (err, assigned) => (err ? reject(err) : resolve(assigned)), + ); + }); + this.server = server; + this.port = bound; + return this.address; + } + + /** + * Stop listening. A client now gets a refused connection, which is + * the "hub not reachable" case: no error class, `reachedHub` false. + * + * The shutdown is forced on purpose. A graceful one waits for calls + * in flight, and a run parked at an approval never finishes, so a + * graceful stop would hang exactly where a crash is being modelled. + */ + async stop(): Promise { + const server = this.server; + if (!server) return; + this.server = undefined; + this.dropWaiters('the hub went down while this run was waiting'); + // Let those answers leave before the socket does. Without the + // tick, forceShutdown cancels the calls first and a caller learns + // "cancelled" instead of "the hub is gone", which is the wrong + // story for a gateway deciding whether to start the run again. + await new Promise((resolve) => setTimeout(resolve, 10)); + server.forceShutdown(); + } + + /** Fail every run parked at an approval. */ + private dropWaiters(message: string): void { + for (const waiter of [...this.waiters.values()]) { + this.waiters.delete(waiter.approvalId); + waiter.settle({ ok: false, kind: 'unavailable', message }); + } + } + + /** + * Stop and start again on the same port, losing what the real hub + * loses: running and waiting runs. Approvals stay, so a test can + * check that a decision after a restart no longer resumes anything. + */ + async restart(): Promise { + await this.stop(); + this.runs.clear(); + return this.start(this.port); + } + + /** Shut down for good. */ + async close(): Promise { + await this.stop(); + this.port = 0; + } + + private nextBehaviour(): Behaviour { + return this.script.shift() ?? this.fallback; + } + + private recordSubmit(call: { request: Record }, invocationId: string): RecordedSubmit { + const request = call.request; + const inputs: Record = {}; + for (const [name, payload] of Object.entries( + (request.inputs ?? {}) as Record, + )) { + inputs[name] = payloadFromWire(payload); + } + const yaml = request.flowYaml; + const recorded: RecordedSubmit = { + flowYaml: Buffer.isBuffer(yaml) ? yaml.toString('utf8') : String(yaml ?? ''), + inputs, + project: String(request.project ?? ''), + detach: Boolean(request.detach), + idempotencyKey: String(request.idempotencyKey ?? ''), + invocationId, + }; + this.submits.push(recorded); + return recorded; + } + + private flowNameOf(yaml: string): string { + const m = /^\s*name:\s*(\S+)/m.exec(yaml); + return m?.[1] ?? 'flow'; + } + + private openApproval( + behaviour: AwaitApprovalBehaviour, + recorded: RecordedSubmit, + ): PendingApproval { + const approval: PendingApproval = { + approvalId: nextId('approval'), + flowExecution: recorded.invocationId, + flowName: this.flowNameOf(recorded.flowYaml), + stepId: behaviour.stepId ?? 'approval', + prompt: behaviour.prompt, + createdAt: nowIso(), + status: 'PENDING', + decidedAt: '', + decidedBy: '', + reason: '', + project: recorded.project, + }; + this.approvals.push(approval); + return approval; + } + + private hubHandlers(): grpc.UntypedServiceImplementation { + return { + health: (_call: grpc.ServerUnaryCall, unknown>, callback: grpc.sendUnaryData) => { + callback(null, { state: this.health, detail: 'fake hub' }); + }, + listModules: (_call: grpc.ServerUnaryCall, unknown>, callback: grpc.sendUnaryData) => { + callback(null, { modules: [] }); + }, + listInvocations: (_call: grpc.ServerUnaryCall, unknown>, callback: grpc.sendUnaryData) => { + callback(null, { invocations: [] }); + }, + submit: (call: grpc.ServerUnaryCall, unknown>, callback: grpc.sendUnaryData) => { + void this.handleSubmit(call as { request: Record }, callback); + }, + submitStream: (call: grpc.ServerWritableStream, unknown>) => { + void this.handleSubmitStream(call); + }, + getInvocationStatus: (call: grpc.ServerUnaryCall, unknown>, callback: grpc.sendUnaryData) => { + const id = String((call as { request: { value?: string } }).request.value ?? ''); + const run = this.runs.get(id); + if (!run) { + callback(errorFor('not_found', `unknown invocation '${id}'`)); + return; + } + callback(null, { + phase: run.phase, + currentStep: run.currentStep, + startedAt: run.startedAt, + finishedAt: run.finishedAt, + error: run.error, + }); + }, + getInvocationResult: (call: grpc.ServerUnaryCall, unknown>, callback: grpc.sendUnaryData) => { + const id = String((call as { request: { value?: string } }).request.value ?? ''); + const run = this.runs.get(id); + if (!run) { + callback(errorFor('not_found', `no retained result for '${id}'`)); + return; + } + if (run.phase === 'RUNNING' || run.phase === 'PENDING') { + callback(errorFor('precondition', `invocation '${id}' is still running`)); + return; + } + if (run.phase === 'FAILED') { + callback(errorFor('step_failed', run.error)); + return; + } + callback(null, { + invocationId: { value: id }, + outputs: wireOutputs(run.outputs), + }); + }, + cancelInvocation: (call: grpc.ServerUnaryCall, unknown>, callback: grpc.sendUnaryData) => { + const id = String((call as { request: { value?: string } }).request.value ?? ''); + const run = this.runs.get(id); + const cancellable = run?.phase === 'RUNNING' || run?.phase === 'PENDING'; + if (run && cancellable) { + run.phase = 'CANCELLED'; + run.finishedAt = nowIso(); + const waiter = [...this.waiters.values()].find((w) => w.invocationId === id); + if (waiter) { + this.waiters.delete(waiter.approvalId); + waiter.settle({ ok: false, kind: 'cancelled', message: 'cancelled by the caller' }); + } + } + callback(null, { cancelled: Boolean(run && cancellable) }); + }, + }; + } + + private async handleSubmit( + call: { request: Record }, + callback: grpc.sendUnaryData, + ): Promise { + const key = String(call.request.idempotencyKey ?? ''); + const project = String(call.request.project ?? ''); + const scope = `${project}\u0000${key}`; + if (key && this.keys.has(scope)) { + const id = this.keys.get(scope) as string; + const run = this.runs.get(id); + this.recordSubmit(call, id); + callback(null, { + invocationId: { value: id }, + outputs: wireOutputs(run?.outputs ?? {}), + }); + return; + } + + const invocationId = nextId('run'); + if (key) this.keys.set(scope, invocationId); + const recorded = this.recordSubmit(call, invocationId); + const behaviour = this.nextBehaviour(); + const detach = recorded.detach; + + if (behaviour.type === 'fail') { + if (detach) { + this.runs.set(invocationId, { + phase: 'FAILED', + currentStep: '', + startedAt: nowIso(), + finishedAt: nowIso(), + error: behaviour.message, + outputs: {}, + }); + callback(null, { invocationId: { value: invocationId }, outputs: {} }); + return; + } + callback(errorFor(behaviour.kind, behaviour.message)); + return; + } + + if (behaviour.type === 'succeed') { + const outputs = behaviour.outputs ?? {}; + this.runs.set(invocationId, { + phase: 'SUCCEEDED', + currentStep: '', + startedAt: nowIso(), + finishedAt: nowIso(), + error: '', + outputs, + }); + callback(null, { + invocationId: { value: invocationId }, + outputs: detach ? {} : wireOutputs(outputs), + }); + return; + } + + // awaitApproval + const approval = this.openApproval(behaviour, recorded); + this.runs.set(invocationId, { + phase: 'RUNNING', + currentStep: approval.stepId, + startedAt: nowIso(), + finishedAt: '', + error: '', + outputs: {}, + }); + if (detach) { + // A detached run returns its id and keeps waiting. + callback(null, { invocationId: { value: invocationId }, outputs: {} }); + this.awaitDecision(approval, invocationId, behaviour.outputs ?? {}).catch(() => {}); + return; + } + const outcome = await this.awaitDecision(approval, invocationId, behaviour.outputs ?? {}); + if (outcome.ok) { + callback(null, { + invocationId: { value: invocationId }, + outputs: wireOutputs(outcome.outputs), + }); + } else { + callback(errorFor(outcome.kind, outcome.message)); + } + } + + private awaitDecision( + approval: PendingApproval, + invocationId: string, + outputs: Record, + ): Promise<{ ok: true; outputs: Record } | { ok: false; kind: ChainErrorKind; message: string }> { + return new Promise((resolve) => { + this.waiters.set(approval.approvalId, { + approvalId: approval.approvalId, + invocationId, + outputs, + settle: (outcome) => { + const run = this.runs.get(invocationId); + if (run) { + run.phase = outcome.ok ? 'SUCCEEDED' : 'FAILED'; + run.currentStep = ''; + run.finishedAt = nowIso(); + run.error = outcome.ok ? '' : outcome.message; + run.outputs = outcome.ok ? outcome.outputs : {}; + } + resolve(outcome); + }, + }); + }); + } + + private async handleSubmitStream( + call: grpc.ServerWritableStream, unknown>, + ): Promise { + const invocationId = nextId('run'); + const recorded = this.recordSubmit(call, invocationId); + const behaviour = this.nextBehaviour(); + + const steps = behaviour.type === 'fail' ? [] : (behaviour.steps ?? []); + for (const step of steps) { + call.write({ stepStarted: { step, capability: 'fake/step@^1' } }); + call.write({ stepFinished: { step, ok: true, durationMs: 1 } }); + } + + if (behaviour.type === 'fail') { + call.write({ error: { message: behaviour.message, kind: behaviour.kind } }); + call.end(); + return; + } + if (behaviour.type === 'succeed') { + call.write({ + finalResult: { + invocationId: { value: invocationId }, + outputs: wireOutputs(behaviour.outputs ?? {}), + }, + }); + call.end(); + return; + } + + const approval = this.openApproval(behaviour, recorded); + this.runs.set(invocationId, { + phase: 'RUNNING', + currentStep: approval.stepId, + startedAt: nowIso(), + finishedAt: '', + error: '', + outputs: {}, + }); + const outcome = await this.awaitDecision(approval, invocationId, behaviour.outputs ?? {}); + if (outcome.ok) { + call.write({ + finalResult: { + invocationId: { value: invocationId }, + outputs: wireOutputs(outcome.outputs), + }, + }); + } else { + call.write({ error: { message: outcome.message, kind: outcome.kind } }); + } + call.end(); + } + + private adminHandlers(): grpc.UntypedServiceImplementation { + const notImplemented = (_call: unknown, callback: grpc.sendUnaryData) => { + callback(errorFor('precondition', 'the fake hub does not implement this RPC')); + }; + const handlers: grpc.UntypedServiceImplementation = { + listApprovals: (call: grpc.ServerUnaryCall, unknown>, callback: grpc.sendUnaryData) => { + const request = (call as { request: { statuses?: string[]; project?: string; limit?: number } }) + .request; + const wanted = (request.statuses ?? ['PENDING']).map((s) => s.toUpperCase()); + const project = request.project ?? ''; + const entries = this.approvals + .filter((a) => wanted.length === 0 || wanted.includes(a.status)) + .filter((a) => !project || a.project === project) + .slice(0, request.limit && request.limit > 0 ? request.limit : 100) + .map((a) => ({ + approvalId: a.approvalId, + flowExecution: a.flowExecution, + flowName: a.flowName, + stepId: a.stepId, + prompt: a.prompt, + payloadPreview: '', + createdAt: a.createdAt, + expiresAt: '', + status: a.status, + decidedAt: a.decidedAt, + decidedBy: a.decidedBy, + reason: a.reason, + project: a.project, + })); + callback(null, { entries }); + }, + decideApproval: (call: grpc.ServerUnaryCall, unknown>, callback: grpc.sendUnaryData) => { + const request = ( + call as { + request: { approvalId?: string; decision?: string; reviewer?: string; reason?: string }; + } + ).request; + const approvalId = String(request.approvalId ?? ''); + const decision = String(request.decision ?? '').toUpperCase(); + const reviewer = String(request.reviewer ?? ''); + const reason = String(request.reason ?? ''); + this.decisions.push({ approvalId, decision, reviewer, reason }); + + const approval = this.approvals.find((a) => a.approvalId === approvalId); + if (!approval) { + callback(errorFor('not_found', `approval '${approvalId}' not found`)); + return; + } + if (approval.status !== 'PENDING') { + callback( + errorFor('precondition', `approval '${approvalId}' is already ${approval.status}`), + ); + return; + } + if (decision === 'REJECT' && !reason) { + callback(errorFor('flow_rejected', 'reason required for REJECT')); + return; + } + approval.status = decision === 'APPROVE' ? 'APPROVED' : 'REJECTED'; + approval.decidedAt = nowIso(); + approval.decidedBy = reviewer; + approval.reason = reason; + + const waiter = this.waiters.get(approvalId); + this.waiters.delete(approvalId); + if (waiter) { + if (approval.status === 'APPROVED') { + waiter.settle({ ok: true, outputs: waiter.outputs }); + } else { + waiter.settle({ + ok: false, + kind: 'approval_rejected', + message: `step '${approval.stepId}' was rejected by ${reviewer}: ${reason}`, + }); + } + } + callback(null, { approvalId, status: approval.status }); + }, + }; + // Every other HubAdmin RPC answers with a clear refusal rather + // than hanging, so a test that strays finds out immediately. + // + // The definition keys the methods by their proto name + // (`ListApprovals`) and carries the camelCase name as + // `originalName`. grpc-js looks up the proto name first, so a + // fallback registered under it would shadow a handler written in + // camelCase. Both spellings are therefore checked. + for (const [name, definition] of Object.entries(hubAdminServiceDefinition())) { + const camel = (definition as { originalName?: string }).originalName; + if (handlers[name] || (camel && handlers[camel])) continue; + handlers[name] = notImplemented; + } + return handlers; + } +} diff --git a/src/index.ts b/src/index.ts new file mode 100644 index 0000000..d940579 --- /dev/null +++ b/src/index.ts @@ -0,0 +1,44 @@ +// Public surface of the TypeScript client. + +export { + ChainClient, + type Approval, + type ChainClientOptions, + type DecideApprovalOptions, + type FlowEvent, + type FlowResult, + type HubHealth, + type InvocationStatus, + type SubmitOptions, + type TlsOptions, +} from './client.js'; +export { + ChainError, + type ChainErrorFamily, + type ChainErrorInit, + type ChainErrorKind, + ERROR_KIND_KEY, + asKind, + chainErrorFrom, + kindForCode, +} from './errors.js'; +export { + asBytes, + asJson, + asText, + type PayloadInput, + type PayloadOutput, + payloadFromWire, + payloadToWire, + structFromWire, + structToWire, +} from './payload.js'; +export { + chainProto, + hubAdminServiceConstructor, + hubAdminServiceDefinition, + hubServiceConstructor, + hubServiceDefinition, + protoDir, + protoFiles, +} from './proto.js'; diff --git a/src/payload.ts b/src/payload.ts new file mode 100644 index 0000000..8d81d9c --- /dev/null +++ b/src/payload.ts @@ -0,0 +1,204 @@ +// Payload conversion between plain JavaScript and `chain.v1.Payload`. +// +// `google.protobuf.Struct` is not plain JSON on the wire, so the +// conversion is written out here rather than left to the proto +// loader: both directions are covered by tests, and a `null` inside a +// nested object stays a `null` instead of turning into an empty +// object. + +/** What a caller may pass as a flow input. */ +export type PayloadInput = + | string + | { text: string } + | { json: unknown } + | { bytes: Uint8Array; mimeType?: string } + | { file: { uri: string; mimeType?: string; sizeBytes?: number; sha256?: string } } + | Record + | unknown[]; + +/** What a flow output turns into. */ +export type PayloadOutput = + | { kind: 'text'; text: string } + | { kind: 'json'; json: unknown } + | { kind: 'bytes'; mimeType: string; data: Buffer } + | { kind: 'file'; uri: string; mimeType: string; sizeBytes: number; sha256: string } + | { kind: 'empty' }; + +/** Wire shape of `google.protobuf.Value`. */ +interface WireValue { + nullValue?: number | null; + numberValue?: number; + stringValue?: string; + boolValue?: boolean; + structValue?: WireStruct; + listValue?: { values?: WireValue[] }; + kind?: string; +} + +/** Wire shape of `google.protobuf.Struct`. */ +interface WireStruct { + fields?: Record; +} + +/** Wire shape of `chain.v1.Payload`. */ +export interface WirePayload { + text?: string; + json?: WireStruct; + bytes?: { mimeType?: string; data?: Buffer | Uint8Array }; + file?: { uri?: string; mimeType?: string; sizeBytes?: number | string; sha256?: string }; + kind?: string; +} + +function valueToWire(value: unknown): WireValue { + if (value === null || value === undefined) return { nullValue: 0 }; + switch (typeof value) { + case 'string': + return { stringValue: value }; + case 'number': + if (!Number.isFinite(value)) { + throw new TypeError(`json inputs cannot carry ${String(value)}`); + } + return { numberValue: value }; + case 'boolean': + return { boolValue: value }; + case 'bigint': + return { numberValue: Number(value) }; + default: + break; + } + if (Array.isArray(value)) { + return { listValue: { values: value.map(valueToWire) } }; + } + if (value instanceof Date) { + return { stringValue: value.toISOString() }; + } + return { structValue: structToWire(value as Record) }; +} + +/** Convert a plain object into a `google.protobuf.Struct`. */ +export function structToWire(obj: Record): WireStruct { + const fields: Record = {}; + for (const [key, value] of Object.entries(obj)) { + if (value === undefined) continue; + fields[key] = valueToWire(value); + } + return { fields }; +} + +function valueFromWire(value: WireValue | undefined): unknown { + if (!value) return null; + if (value.stringValue !== undefined) return value.stringValue; + if (value.numberValue !== undefined) return value.numberValue; + if (value.boolValue !== undefined) return value.boolValue; + if (value.structValue !== undefined) return structFromWire(value.structValue); + if (value.listValue !== undefined) { + return (value.listValue.values ?? []).map(valueFromWire); + } + return null; +} + +/** Convert a `google.protobuf.Struct` into a plain object. */ +export function structFromWire(struct: WireStruct | undefined): Record { + const out: Record = {}; + for (const [key, value] of Object.entries(struct?.fields ?? {})) { + out[key] = valueFromWire(value); + } + return out; +} + +function isTagged(value: object, key: string): boolean { + return Object.prototype.hasOwnProperty.call(value, key); +} + +/** + * Convert a caller's input into a wire payload. + * + * A string is text. An object tagged `text`, `json`, `bytes` or + * `file` is that kind. Any other object or array is sent as `json`, + * because that is what a caller means by passing one. + */ +export function payloadToWire(input: PayloadInput): WirePayload { + if (typeof input === 'string') return { text: input }; + if (typeof input === 'number' || typeof input === 'boolean') { + return { text: String(input) }; + } + if (input === null || input === undefined) return { text: '' }; + if (Array.isArray(input)) { + throw new TypeError( + 'a bare array is not a payload: pass { json: [...] } so the kind is explicit', + ); + } + const obj = input as Record; + if (isTagged(obj, 'text')) return { text: String(obj.text ?? '') }; + if (isTagged(obj, 'json')) { + const json = obj.json; + if (json === null || typeof json !== 'object' || Array.isArray(json)) { + throw new TypeError( + 'json payloads are objects: the hub carries google.protobuf.Struct, which has named fields', + ); + } + return { json: structToWire(json as Record) }; + } + if (isTagged(obj, 'bytes')) { + const bytes = obj.bytes as Uint8Array; + const mimeType = typeof obj.mimeType === 'string' ? obj.mimeType : 'application/octet-stream'; + return { bytes: { mimeType, data: Buffer.from(bytes) } }; + } + if (isTagged(obj, 'file')) { + const file = obj.file as { uri: string; mimeType?: string; sizeBytes?: number; sha256?: string }; + return { + file: { + uri: file.uri, + mimeType: file.mimeType ?? '', + sizeBytes: file.sizeBytes ?? 0, + sha256: file.sha256 ?? '', + }, + }; + } + return { json: structToWire(obj) }; +} + +/** Convert a wire payload into something a caller can read. */ +export function payloadFromWire(payload: WirePayload | undefined): PayloadOutput { + if (!payload) return { kind: 'empty' }; + // The loader names the set member of the oneof in `kind`; trust it + // over key presence, so a hub that starts sending defaults cannot + // make a text payload look like json as well. + if (payload.kind === 'text') return { kind: 'text', text: payload.text ?? '' }; + if (payload.text !== undefined) return { kind: 'text', text: payload.text }; + if (payload.json !== undefined) { + return { kind: 'json', json: structFromWire(payload.json) }; + } + if (payload.bytes !== undefined) { + return { + kind: 'bytes', + mimeType: payload.bytes.mimeType ?? '', + data: Buffer.from(payload.bytes.data ?? new Uint8Array()), + }; + } + if (payload.file !== undefined) { + return { + kind: 'file', + uri: payload.file.uri ?? '', + mimeType: payload.file.mimeType ?? '', + sizeBytes: Number(payload.file.sizeBytes ?? 0), + sha256: payload.file.sha256 ?? '', + }; + } + return { kind: 'empty' }; +} + +/** The text of a payload, or `undefined` when it is another kind. */ +export function asText(payload: PayloadOutput | undefined): string | undefined { + return payload?.kind === 'text' ? payload.text : undefined; +} + +/** The object of a json payload, or `undefined` when it is another kind. */ +export function asJson(payload: PayloadOutput | undefined): unknown | undefined { + return payload?.kind === 'json' ? payload.json : undefined; +} + +/** The bytes of a payload, or `undefined` when it is another kind. */ +export function asBytes(payload: PayloadOutput | undefined): Buffer | undefined { + return payload?.kind === 'bytes' ? payload.data : undefined; +} diff --git a/src/proto.ts b/src/proto.ts new file mode 100644 index 0000000..5422209 --- /dev/null +++ b/src/proto.ts @@ -0,0 +1,111 @@ +// Loading the `chain.v1` contract. +// +// The `.proto` files are carried verbatim from the platform repo and +// loaded at runtime, so there is no generated code that can drift +// from them. `scripts/sync-proto.mjs` refreshes the copies and +// records their hashes; `test/proto_copy.test.ts` guards them. + +import * as fs from 'node:fs'; +import * as path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +import * as grpc from '@grpc/grpc-js'; +import * as protoLoader from '@grpc/proto-loader'; + +const moduleDir = path.dirname(fileURLToPath(import.meta.url)); + +/** + * Find the `proto` directory by walking up from this file. + * + * The compiled module sits in `dist/`, a test build in + * `build-test/src/`, and the sources in `src/`. Guessing a fixed + * number of levels up breaks one of the three, so the directory is + * searched for by what it contains. + */ +function findProtoDir(): string { + let dir = moduleDir; + for (let i = 0; i < 6; i += 1) { + const candidate = path.join(dir, 'proto'); + if (fs.existsSync(path.join(candidate, 'chain', 'v1', 'common.proto'))) { + return candidate; + } + const parent = path.dirname(dir); + if (parent === dir) break; + dir = parent; + } + throw new Error( + `proto/chain/v1 not found above ${moduleDir}: the package ships the .proto files, so this is a packaging fault`, + ); +} + +/** Directory holding the verbatim `chain.v1` copies. */ +export const protoDir = findProtoDir(); + +/** The files that make up the contract. */ +export const protoFiles = [ + 'chain/v1/common.proto', + 'chain/v1/hub.proto', + 'chain/v1/module.proto', + 'chain/v1/federation.proto', +] as const; + +/** + * Loader options, shared by the client and the fake hub so both speak + * the same shapes. + * + * `defaults: false` matters: with defaults on, every member of a + * `oneof` would come back present, and a payload would look like text + * and json at once. + */ +const loaderOptions: protoLoader.Options = { + keepCase: false, + longs: Number, + enums: String, + defaults: false, + oneofs: true, + includeDirs: [protoDir], +}; + +let cached: grpc.GrpcObject | undefined; + +/** The loaded package, built once per process. */ +export function chainProto(): grpc.GrpcObject { + if (cached) return cached; + const definition = protoLoader.loadSync( + protoFiles.map((f) => path.join(protoDir, f)), + loaderOptions, + ); + cached = grpc.loadPackageDefinition(definition); + return cached; +} + +function serviceConstructor(name: 'Hub' | 'HubAdmin'): grpc.ServiceClientConstructor { + const root = chainProto() as unknown as { + chain: { v1: Record }; + }; + const ctor = root.chain?.v1?.[name]; + if (!ctor) { + throw new Error(`chain.v1.${name} missing from the loaded proto files`); + } + return ctor; +} + +/** Constructor of the `chain.v1.Hub` client. */ +export function hubServiceConstructor(): grpc.ServiceClientConstructor { + return serviceConstructor('Hub'); +} + +/** Constructor of the `chain.v1.HubAdmin` client. */ +export function hubAdminServiceConstructor(): grpc.ServiceClientConstructor { + return serviceConstructor('HubAdmin'); +} + +/** Service definition of `chain.v1.Hub`, for building a server. */ +export function hubServiceDefinition(): grpc.ServiceDefinition { + return hubServiceConstructor().service; +} + +/** Service definition of `chain.v1.HubAdmin`, for building a server. */ +export function hubAdminServiceDefinition(): grpc.ServiceDefinition { + return hubAdminServiceConstructor().service; +} diff --git a/test/client_against_fake.test.ts b/test/client_against_fake.test.ts new file mode 100644 index 0000000..bb01648 --- /dev/null +++ b/test/client_against_fake.test.ts @@ -0,0 +1,277 @@ +// The client against the fake hub: hermetic, no hub binary, no +// module, no model. Every case here is one a portal gateway has to +// survive. + +import assert from 'node:assert/strict'; +import { after, before, beforeEach, describe, it } from 'node:test'; + +import { ChainClient, ChainError, asJson, asText } from '../src/index.js'; +import { FakeHub } from '../src/fake_hub.js'; + +const FLOW = `name: verbrauchsausweis +inputs: + consumption: { type: json } +steps: + - id: score + uses: geg.verbrauch@^1 +outputs: + report: $steps.score.text +`; + +describe('client against the fake hub', () => { + let hub: FakeHub; + let client: ChainClient; + + before(async () => { + hub = new FakeHub(); + const address = await hub.start(); + client = new ChainClient({ address, project: 'helloeco', deadlineMs: 5_000 }); + }); + + after(async () => { + client.close(); + await hub.close(); + }); + + beforeEach(() => { + hub.setFallback({ type: 'succeed', outputs: {} }); + hub.setHealth('SERVING'); + }); + + it('reports health', async () => { + const health = await client.health(); + assert.equal(health.state, 'SERVING'); + }); + + it('runs a flow and reads its outputs', async () => { + hub.succeeds({ report: 'Endenergiebedarf 128 kWh/(m²·a)', data: { json: { class: 'D' } } }); + const result = await client.submit({ + flowYaml: FLOW, + inputs: { consumption: { json: { kwh: 15400 } } }, + }); + assert.equal(asText(result.outputs.report), 'Endenergiebedarf 128 kWh/(m²·a)'); + assert.deepEqual(asJson(result.outputs.data), { class: 'D' }); + assert.match(result.invocationId, /^run-/); + + const seen = hub.submits.at(-1); + assert.equal(seen?.project, 'helloeco'); + assert.deepEqual(seen?.inputs.consumption, { kind: 'json', json: { kwh: 15400 } }); + }); + + it('follows a run step by step', async () => { + hub.succeeds({ report: 'done' }, ['check', 'score', 'render']); + const events = []; + for await (const event of client.submitStream({ flowYaml: FLOW })) { + events.push(event); + } + const started = events.filter((e) => e.type === 'stepStarted').map((e) => e.step); + assert.deepEqual(started, ['check', 'score', 'render']); + const last = events.at(-1); + assert.equal(last?.type, 'result'); + if (last?.type === 'result') { + assert.equal(asText(last.result.outputs.report), 'done'); + } + }); + + it('classifies an overloaded hub as retryable without blaming the request', async () => { + hub.fails('overloaded', 'too many runs in flight'); + const err = await client.submit({ flowYaml: FLOW }).then( + () => undefined, + (e: unknown) => e as ChainError, + ); + assert.ok(err instanceof ChainError); + assert.equal(err.kind, 'overloaded'); + assert.equal(err.family, 'overloaded'); + assert.equal(err.retryable, true); + assert.equal(err.reachedHub, true); + }); + + it('classifies a refused request as not retryable', async () => { + hub.fails('flow_rejected', "missing value '$inputs.consumption'"); + const err = (await client.submit({ flowYaml: FLOW }).catch((e) => e)) as ChainError; + assert.equal(err.kind, 'flow_rejected'); + assert.equal(err.retryable, false); + }); + + it('carries the class out of a stream too', async () => { + hub.fails('step_failed', "step 'render' failed: template has no page size"); + const err = await (async () => { + try { + for await (const _event of client.submitStream({ flowYaml: FLOW })) { + // drain + } + return undefined; + } catch (e) { + return e as ChainError; + } + })(); + assert.ok(err instanceof ChainError); + assert.equal(err.kind, 'step_failed'); + assert.equal(err.family, 'failed'); + assert.equal(err.step, 'render'); + }); + + it('returns the same run for the same idempotency key', async () => { + hub.succeeds({ report: 'first' }); + hub.succeeds({ report: 'second' }); + const first = await client.submit({ flowYaml: FLOW, idempotencyKey: 'stripe-evt-1' }); + const again = await client.submit({ flowYaml: FLOW, idempotencyKey: 'stripe-evt-1' }); + assert.equal(again.invocationId, first.invocationId); + assert.equal(asText(again.outputs.report), 'first'); + // The second submit must not have consumed the next scripted run. + const third = await client.submit({ flowYaml: FLOW, idempotencyKey: 'stripe-evt-2' }); + assert.equal(asText(third.outputs.report), 'second'); + assert.notEqual(third.invocationId, first.invocationId); + }); + + it('waits for an approval, then finishes with the reviewer on record', async () => { + hub.waitsForApproval({ + prompt: 'Registriernummer 4711 vergeben und Ausweis zustellen?', + stepId: 'freigabe', + outputs: { report: 'zugestellt' }, + }); + const run = client.submit({ flowYaml: FLOW }); + + const pending = await waitFor(async () => { + const list = await client.listApprovals({ project: 'helloeco' }); + return list.length > 0 ? list : undefined; + }); + assert.equal(pending[0]?.prompt, 'Registriernummer 4711 vergeben und Ausweis zustellen?'); + assert.equal(pending[0]?.stepId, 'freigabe'); + + await client.decideApproval({ + approvalId: pending[0]!.approvalId, + approve: true, + reviewer: 'aussteller@example.org', + }); + + const result = await run; + assert.equal(asText(result.outputs.report), 'zugestellt'); + assert.equal(hub.decisions.at(-1)?.reviewer, 'aussteller@example.org'); + }); + + it('fails the run when the reviewer declines, with the reason', async () => { + hub.waitsForApproval({ prompt: 'Ausweis zustellen?', outputs: {} }); + // The catch is attached right away: the run rejects while the + // test is still waiting for the approval row, and an unhandled + // rejection in between would fail the test for the wrong reason. + const run = client.submit({ flowYaml: FLOW }).catch((e: unknown) => e as ChainError); + const pending = await waitFor(async () => { + const list = await client.listApprovals(); + return list.length > 0 ? list : undefined; + }); + await client.decideApproval({ + approvalId: pending[0]!.approvalId, + approve: false, + reviewer: 'aussteller@example.org', + reason: 'Verbrauchswerte unplausibel', + }); + const err = (await run) as ChainError; + assert.equal(err.kind, 'approval_rejected'); + assert.match(err.message, /unplausibel/); + }); + + it('refuses a rejection without a reason', async () => { + hub.waitsForApproval({ prompt: 'Ausweis zustellen?', outputs: {} }); + const run = client.submit({ flowYaml: FLOW }).catch((e: unknown) => e as ChainError); + const pending = await waitFor(async () => { + const list = await client.listApprovals(); + return list.length > 0 ? list : undefined; + }); + const err = (await client + .decideApproval({ approvalId: pending[0]!.approvalId, approve: false }) + .catch((e) => e)) as ChainError; + assert.equal(err.kind, 'flow_rejected'); + await client.decideApproval({ + approvalId: pending[0]!.approvalId, + approve: false, + reason: 'aufgeräumt', + }); + await run; + }); + + it('follows a detached run by id', async () => { + hub.succeeds({ report: 'spät' }); + const started = await client.submit({ flowYaml: FLOW, detach: true }); + assert.deepEqual(started.outputs, {}); + const status = await client.getStatus(started.invocationId); + assert.equal(status.phase, 'SUCCEEDED'); + const result = await client.getResult(started.invocationId); + assert.equal(asText(result.outputs.report), 'spät'); + }); + + it('says not_found for an invocation the hub never had', async () => { + const err = (await client.getStatus('run-does-not-exist').catch((e) => e)) as ChainError; + assert.equal(err.kind, 'not_found'); + assert.equal(err.family, 'rejected'); + }); +}); + +describe('client against a hub that is not there', () => { + it('says the hub was never reached, not that a dependency failed', async () => { + const hub = new FakeHub(); + const address = await hub.start(); + const client = new ChainClient({ address, deadlineMs: 2_000 }); + await client.health(); + await hub.stop(); + + const err = (await client.health().catch((e) => e)) as ChainError; + assert.equal(err.family, 'unreachable'); + assert.equal(err.reachedHub, false); + assert.equal(err.retryable, true); + client.close(); + await hub.close(); + }); +}); + +describe('a hub restart while a run waits for an approval', () => { + it('loses the run, keeps the approval, and says so', async () => { + // This is today's platform behaviour, not a wish: run state lives + // in memory, approvals live in SQLite. A gateway must therefore + // treat "approval still pending after a restart" as a run it has + // to start again. + const hub = new FakeHub(); + const address = await hub.start(); + const client = new ChainClient({ address, project: 'helloeco', deadlineMs: 5_000 }); + + hub.waitsForApproval({ prompt: 'Ausweis zustellen?', outputs: { report: 'zugestellt' } }); + const run = client.submit({ flowYaml: FLOW }).catch((e: unknown) => e as ChainError); + const pending = await waitFor(async () => { + const list = await client.listApprovals({ project: 'helloeco' }); + return list.length > 0 ? list : undefined; + }); + const approvalId = pending[0]!.approvalId; + + await hub.restart(); + + const err = (await run) as ChainError; + assert.equal(err.family, 'unreachable'); + + // The decision still lands, and still has nothing to resume. + const stillPending = await client.listApprovals({ project: 'helloeco' }); + assert.equal(stillPending.length, 1); + assert.equal(stillPending[0]?.approvalId, approvalId); + const decided = await client.decideApproval({ + approvalId, + approve: true, + reviewer: 'aussteller@example.org', + }); + assert.equal(decided.status, 'APPROVED'); + const gone = (await client.getStatus(pending[0]!.flowExecution).catch((e) => e)) as ChainError; + assert.equal(gone.kind, 'not_found'); + + client.close(); + await hub.close(); + }); +}); + +/** Poll until the producer returns something, or give up. */ +async function waitFor(produce: () => Promise, timeoutMs = 3_000): Promise { + const until = Date.now() + timeoutMs; + for (;;) { + const value = await produce(); + if (value !== undefined) return value; + if (Date.now() > until) throw new Error('timed out waiting for the fake hub'); + await new Promise((resolve) => setTimeout(resolve, 20)); + } +} diff --git a/test/errors.test.ts b/test/errors.test.ts new file mode 100644 index 0000000..fa58ecb --- /dev/null +++ b/test/errors.test.ts @@ -0,0 +1,105 @@ +import assert from 'node:assert/strict'; +import { describe, it } from 'node:test'; + +import { status as GrpcStatus, Metadata } from '@grpc/grpc-js'; +import type { ServiceError } from '@grpc/grpc-js'; + +import { ChainError, chainErrorFrom, kindForCode } from '../src/errors.js'; + +function serviceError(code: number, details: string, kind?: string): ServiceError { + const metadata = new Metadata(); + if (kind) metadata.set('chain-error-kind', kind); + const err = new Error(details) as ServiceError; + err.code = code; + err.details = details; + err.metadata = metadata; + return err; +} + +describe('error classification', () => { + it('prefers the class the hub sent over the gRPC code', () => { + // Both arrive as INVALID_ARGUMENT. Only the class separates + // "fix your request" from "the module ran and said no". + const rejected = chainErrorFrom( + serviceError(GrpcStatus.INVALID_ARGUMENT, "missing value '$inputs.x'", 'flow_rejected'), + ); + const failed = chainErrorFrom( + serviceError(GrpcStatus.INVALID_ARGUMENT, "step 'render' failed", 'step_failed'), + ); + assert.equal(rejected.kind, 'flow_rejected'); + assert.equal(rejected.family, 'rejected'); + assert.equal(failed.kind, 'step_failed'); + assert.equal(failed.family, 'failed'); + assert.equal(failed.step, 'render'); + }); + + it('tells a hub that is not reachable from a dependency that is down', () => { + const noHub = chainErrorFrom(serviceError(GrpcStatus.UNAVAILABLE, 'No connection established')); + const hubSaysSo = chainErrorFrom( + serviceError(GrpcStatus.UNAVAILABLE, "service 'ollama' did not answer", 'unavailable'), + ); + assert.equal(noHub.reachedHub, false); + assert.equal(hubSaysSo.reachedHub, true); + // Both are retryable, but only one is the hub's own fault. + assert.equal(noHub.retryable, true); + assert.equal(hubSaysSo.retryable, true); + }); + + it('reads a cancellation it did not cause as a lost hub', () => { + // grpc-js reports CANCELLED when the transport drops a call in + // flight. Without a class the hub never produced that status, and + // a gateway must not read it as "I cancelled this myself". + const err = chainErrorFrom(serviceError(GrpcStatus.CANCELLED, 'Call cancelled')); + assert.equal(err.kind, 'unavailable'); + assert.equal(err.family, 'unreachable'); + assert.equal(err.reachedHub, false); + // A cancellation the hub itself reports keeps its class. + const fromHub = chainErrorFrom( + serviceError(GrpcStatus.CANCELLED, 'cancelled by the caller', 'cancelled'), + ); + assert.equal(fromHub.kind, 'cancelled'); + }); + + it('keeps an unknown class from a newer hub instead of crashing', () => { + const err = chainErrorFrom( + serviceError(GrpcStatus.INTERNAL, 'something new', 'quantum_entanglement'), + ); + assert.equal(err.kind, 'unknown'); + assert.equal(err.family, 'internal'); + assert.equal(err.reachedHub, true); + }); + + it('maps every gRPC code a hub can send', () => { + assert.equal(kindForCode(GrpcStatus.INVALID_ARGUMENT), 'flow_rejected'); + assert.equal(kindForCode(GrpcStatus.NOT_FOUND), 'not_found'); + assert.equal(kindForCode(GrpcStatus.ALREADY_EXISTS), 'conflict'); + assert.equal(kindForCode(GrpcStatus.FAILED_PRECONDITION), 'precondition'); + assert.equal(kindForCode(GrpcStatus.UNAVAILABLE), 'unavailable'); + assert.equal(kindForCode(GrpcStatus.RESOURCE_EXHAUSTED), 'overloaded'); + assert.equal(kindForCode(GrpcStatus.DEADLINE_EXCEEDED), 'timeout'); + assert.equal(kindForCode(GrpcStatus.PERMISSION_DENIED), 'forbidden'); + assert.equal(kindForCode(GrpcStatus.UNAUTHENTICATED), 'unauthenticated'); + assert.equal(kindForCode(GrpcStatus.CANCELLED), 'cancelled'); + assert.equal(kindForCode(GrpcStatus.INTERNAL), 'internal'); + }); + + it('only marks the three families a retry can help', () => { + const retryable = ['unavailable', 'overloaded', 'timeout'] as const; + for (const kind of retryable) { + assert.equal(new ChainError('x', { kind, code: 0, reachedHub: true }).retryable, true, kind); + } + for (const kind of ['flow_rejected', 'step_failed', 'forbidden', 'internal'] as const) { + assert.equal(new ChainError('x', { kind, code: 0, reachedHub: true }).retryable, false, kind); + } + }); + + it('logs one line without the payload', () => { + const err = new ChainError("step 'render' failed", { + kind: 'step_failed', + code: 3, + reachedHub: true, + step: 'render', + }); + assert.equal(String(err), "ChainError[step_failed/failed] step 'render' failed step=render"); + }); +}); diff --git a/test/payload.test.ts b/test/payload.test.ts new file mode 100644 index 0000000..f3382e7 --- /dev/null +++ b/test/payload.test.ts @@ -0,0 +1,74 @@ +import assert from 'node:assert/strict'; +import { describe, it } from 'node:test'; + +import { asBytes, asJson, asText, payloadFromWire, payloadToWire } from '../src/payload.js'; + +describe('payload conversion', () => { + it('sends a string as text', () => { + assert.deepEqual(payloadToWire('hello'), { text: 'hello' }); + assert.equal(asText(payloadFromWire({ text: 'hello' })), 'hello'); + }); + + it('carries a nested object through google.protobuf.Struct', () => { + const input = { + json: { + owner: { name: 'Haus 12', built: 1974 }, + rooms: [{ area: 24.5 }, { area: 18 }], + heated: true, + note: null, + }, + }; + const wire = payloadToWire(input); + const back = asJson(payloadFromWire(wire)); + assert.deepEqual(back, input.json); + }); + + it('treats a plain object as json, because that is what a caller means', () => { + const wire = payloadToWire({ consumption: 120 }); + assert.deepEqual(asJson(payloadFromWire(wire)), { consumption: 120 }); + }); + + it('refuses a bare array, so the kind stays explicit', () => { + assert.throws(() => payloadToWire([1, 2, 3]), /not a payload/); + }); + + it('refuses a json payload that is not an object', () => { + assert.throws(() => payloadToWire({ json: 'text' }), /Struct/); + }); + + it('round-trips bytes with their media type', () => { + const data = Buffer.from([1, 2, 3, 4]); + const wire = payloadToWire({ bytes: data, mimeType: 'application/pdf' }); + const out = payloadFromWire(wire); + assert.equal(out.kind, 'bytes'); + assert.deepEqual(asBytes(out), data); + assert.equal(out.kind === 'bytes' ? out.mimeType : '', 'application/pdf'); + }); + + it('round-trips a file reference with its hash', () => { + const wire = payloadToWire({ + file: { + uri: 'file:///var/lib/portal/42.jpg', + mimeType: 'image/jpeg', + sizeBytes: 2048, + sha256: 'ab'.repeat(32), + }, + }); + const out = payloadFromWire(wire); + assert.equal(out.kind, 'file'); + if (out.kind === 'file') { + assert.equal(out.sizeBytes, 2048); + assert.equal(out.sha256, 'ab'.repeat(32)); + } + }); + + it('reads the kind the loader names, not the first key it finds', () => { + const out = payloadFromWire({ kind: 'text', text: 'the answer', json: { fields: {} } }); + assert.equal(out.kind, 'text'); + }); + + it('answers empty for a payload that carries nothing', () => { + assert.equal(payloadFromWire(undefined).kind, 'empty'); + assert.equal(payloadFromWire({}).kind, 'empty'); + }); +}); diff --git a/test/proto_copy.test.ts b/test/proto_copy.test.ts new file mode 100644 index 0000000..08e2146 --- /dev/null +++ b/test/proto_copy.test.ts @@ -0,0 +1,51 @@ +// The copies must stay verbatim. Two guards, because they catch +// different mistakes: +// +// * the recorded hashes catch an edit inside this repo, with no +// platform checkout in sight (hermetic); +// * the comparison against the platform repo catches a contract +// that moved on without the copies, and skips when the checkout +// is not there. + +import assert from 'node:assert/strict'; +import { createHash } from 'node:crypto'; +import { existsSync, readFileSync } from 'node:fs'; +import { join, resolve } from 'node:path'; +import { describe, it } from 'node:test'; + +import { protoDir, protoFiles } from '../src/proto.js'; + +function sha256(path: string): string { + return createHash('sha256').update(readFileSync(path)).digest('hex'); +} + +describe('the chain.v1 copies', () => { + it('match their recorded hashes', () => { + const recorded = new Map(); + for (const line of readFileSync(join(protoDir, 'CHECKSUMS'), 'utf8').split('\n')) { + const m = /^([0-9a-f]{64})\s+(\S+)$/.exec(line.trim()); + if (m) recorded.set(m[2] as string, m[1] as string); + } + assert.equal(recorded.size, protoFiles.length, 'CHECKSUMS lists every file'); + for (const file of protoFiles) { + assert.equal(sha256(join(protoDir, file)), recorded.get(file), `${file} was edited`); + } + }); + + it('match the platform repo, when it is checked out here', (t) => { + const platform = resolve( + process.env.CHAIN_PLATFORM_REPO ?? join(protoDir, '..', '..', 'fai_chain'), + ); + if (!existsSync(join(platform, 'proto', 'chain', 'v1', 'hub.proto'))) { + t.skip(`no platform checkout at ${platform}`); + return; + } + for (const file of protoFiles) { + assert.equal( + sha256(join(protoDir, file)), + sha256(join(platform, 'proto', file)), + `${file} drifted from the platform repo: run scripts/sync-proto.mjs`, + ); + } + }); +}); diff --git a/test/real_hub.test.ts b/test/real_hub.test.ts new file mode 100644 index 0000000..e36454d --- /dev/null +++ b/test/real_hub.test.ts @@ -0,0 +1,127 @@ +// The client against a real hub binary. +// +// This is the skew gate for the TypeScript client: it proves that the +// shapes this client encodes are the shapes the hub decodes, which a +// fake can never prove. It needs a built `chain` binary and therefore +// skips when there is none; CI and release work set `CHAIN_BIN`. +// +// CHAIN_BIN=../fai_chain/target/debug/chain npm test + +import assert from 'node:assert/strict'; +import { spawn, type ChildProcess } from 'node:child_process'; +import { existsSync, mkdtempSync, rmSync } from 'node:fs'; +import { createServer } from 'node:net'; +import { tmpdir } from 'node:os'; +import { join, resolve } from 'node:path'; +import { after, before, describe, it } from 'node:test'; + +import { ChainClient, ChainError, asText, protoDir } from '../src/index.js'; + +// `protoDir` is found by searching, so it is the one path that holds +// whether this runs from `src`, `dist` or a test build. +const sdkRoot = resolve(protoDir, '..'); +const platformRepo = resolve( + process.env.CHAIN_PLATFORM_REPO ?? join(sdkRoot, '..', 'fai_chain'), +); +const hubBinary = resolve(process.env.CHAIN_BIN ?? join(platformRepo, 'target', 'debug', 'chain')); +const modulesDir = join(platformRepo, 'modules'); +const echoWasm = join(modulesDir, 'echo', 'target', 'wasm32-wasip2', 'release', 'echo.wasm'); +const available = existsSync(hubBinary) && existsSync(echoWasm); + +const HELLO = `name: hello +inputs: + name: text +steps: + - id: greet + use: debug.echo@^0 + with: + message: "Hello, $inputs.name" +outputs: + greeting: $greet.echoed +`; + +async function freePort(): Promise { + return new Promise((resolvePort, reject) => { + const server = createServer(); + server.on('error', reject); + server.listen(0, '127.0.0.1', () => { + const address = server.address(); + const port = typeof address === 'object' && address ? address.port : 0; + server.close(() => resolvePort(port)); + }); + }); +} + +describe('client against a real hub', { skip: available ? false : `no hub binary at ${hubBinary}` }, () => { + let hub: ChildProcess | undefined; + let client: ChainClient; + let dataDir = ''; + + before(async () => { + const port = await freePort(); + dataDir = mkdtempSync(join(tmpdir(), 'chain-ts-e2e-')); + hub = spawn( + hubBinary, + ['serve', '--bind', `127.0.0.1:${port}`, '--modules-dir', modulesDir, '--data-dir', join(dataDir, 'chain.db')], + { stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, CHAIN_DATA_DIR: dataDir } }, + ); + client = new ChainClient({ address: `127.0.0.1:${port}`, deadlineMs: 20_000 }); + const until = Date.now() + 30_000; + for (;;) { + try { + const health = await client.health(2_000); + if (health.state === 'SERVING') break; + } catch { + // not up yet + } + if (Date.now() > until) throw new Error('the hub did not start'); + await new Promise((r) => setTimeout(r, 200)); + } + }); + + after(async () => { + client?.close(); + hub?.kill('SIGTERM'); + if (dataDir) rmSync(dataDir, { recursive: true, force: true }); + }); + + it('runs the hello flow and reads the output', async () => { + const result = await client.submit({ flowYaml: HELLO, inputs: { name: 'Ch∆In' } }); + assert.equal(asText(result.outputs.greeting), 'Hello, Ch∆In'); + }); + + it('follows the same flow step by step', async () => { + const steps: string[] = []; + let greeting: string | undefined; + for await (const event of client.submitStream({ flowYaml: HELLO, inputs: { name: 'stream' } })) { + if (event.type === 'stepStarted') steps.push(event.step); + if (event.type === 'result') greeting = asText(event.result.outputs.greeting); + } + assert.deepEqual(steps, ['greet']); + assert.equal(greeting, 'Hello, stream'); + }); + + it('gets the real error class out of a real refusal', async () => { + const err = (await client + .submit({ flowYaml: 'this is not a flow [' }) + .catch((e: unknown) => e)) as ChainError; + assert.ok(err instanceof ChainError); + assert.equal(err.kind, 'flow_rejected'); + assert.equal(err.reachedHub, true); + assert.equal(err.retryable, false); + }); + + it('refuses a flow whose module is not installed, as not_found', async () => { + const err = (await client + .submit({ + flowYaml: `name: nowhere\nsteps:\n - id: x\n use: nothing.at.all/missing@^1\noutputs:\n out: $x.text\n`, + }) + .catch((e: unknown) => e)) as ChainError; + assert.ok(err instanceof ChainError); + assert.equal(err.reachedHub, true); + assert.ok( + err.kind === 'not_found' || err.kind === 'flow_rejected', + `an unknown capability reads as not_found or flow_rejected, got ${err.kind}`, + ); + }); +}); diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..ffa455d --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,21 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "lib": ["ES2022"], + "outDir": "dist", + "rootDir": "src", + "declaration": true, + "declarationMap": true, + "sourceMap": true, + "strict": true, + "noUncheckedIndexedAccess": true, + "exactOptionalPropertyTypes": false, + "noImplicitOverride": true, + "verbatimModuleSyntax": true, + "skipLibCheck": true, + "types": ["node"] + }, + "include": ["src/**/*.ts"] +} diff --git a/tsconfig.test.json b/tsconfig.test.json new file mode 100644 index 0000000..f71186e --- /dev/null +++ b/tsconfig.test.json @@ -0,0 +1,10 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "outDir": "build-test", + "rootDir": ".", + "declaration": false, + "declarationMap": false + }, + "include": ["src/**/*.ts", "test/**/*.ts"] +}