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 <sf@flemming.it>
This commit is contained in:
commit
b6c6cc8295
24 changed files with 5539 additions and 0 deletions
4
.gitignore
vendored
Normal file
4
.gitignore
vendored
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
node_modules/
|
||||
dist/
|
||||
build-test/
|
||||
*.tgz
|
||||
201
LICENSE
Normal file
201
LICENSE
Normal file
|
|
@ -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.
|
||||
139
README.md
Normal file
139
README.md
Normal file
|
|
@ -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.
|
||||
363
package-lock.json
generated
Normal file
363
package-lock.json
generated
Normal file
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
42
package.json
Normal file
42
package.json
Normal file
|
|
@ -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 <chain@flemming.ai>",
|
||||
"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"
|
||||
}
|
||||
}
|
||||
4
proto/CHECKSUMS
Normal file
4
proto/CHECKSUMS
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
98a68dd39de4f98d965baf87eca60acc53bb393bd90ae9feb2c07b98071823d9 chain/v1/common.proto
|
||||
b38ade1faa50cd5e645b040001b3d2e32b287b128556694837a1a30083b8416e chain/v1/hub.proto
|
||||
1b2742775d3abe0bcbdcb4a56c14b434e8547f672ea10a7f648ad14c7e14bef7 chain/v1/module.proto
|
||||
47d3af9df026a40f5f5a76311965f719e3ceb49ad944c4393e02158a0bdb1873 chain/v1/federation.proto
|
||||
59
proto/chain/v1/common.proto
Normal file
59
proto/chain/v1/common.proto
Normal file
|
|
@ -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;
|
||||
}
|
||||
}
|
||||
482
proto/chain/v1/federation.proto
Normal file
482
proto/chain/v1/federation.proto
Normal file
|
|
@ -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<string, Payload> 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<string, Payload> 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;
|
||||
}
|
||||
1756
proto/chain/v1/hub.proto
Normal file
1756
proto/chain/v1/hub.proto
Normal file
File diff suppressed because it is too large
Load diff
45
proto/chain/v1/module.proto
Normal file
45
proto/chain/v1/module.proto
Normal file
|
|
@ -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<string, Payload> inputs = 3;
|
||||
uint64 deadline_ms = 4;
|
||||
}
|
||||
|
||||
message InvokeResponse {
|
||||
oneof result {
|
||||
Success success = 1;
|
||||
ChainError error = 2;
|
||||
}
|
||||
}
|
||||
|
||||
message Success {
|
||||
map<string, Payload> outputs = 1;
|
||||
}
|
||||
|
||||
message ModuleDescriptor {
|
||||
string name = 1;
|
||||
string version = 2;
|
||||
repeated CapabilityRef provides = 3;
|
||||
repeated string permissions = 4;
|
||||
}
|
||||
40
scripts/sync-proto.mjs
Normal file
40
scripts/sync-proto.mjs
Normal file
|
|
@ -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');
|
||||
478
src/client.ts
Normal file
478
src/client.ts
Normal file
|
|
@ -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<string, PayloadInput>;
|
||||
/** 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<string, PayloadOutput>;
|
||||
}
|
||||
|
||||
/** 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<string, WirePayload>;
|
||||
}
|
||||
|
||||
type UnaryCallback<T> = (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<Req, Res>(
|
||||
client: grpc.Client,
|
||||
method: string,
|
||||
request: Req,
|
||||
deadlineMs?: number,
|
||||
): Promise<Res> {
|
||||
return new Promise<Res>((resolve, reject) => {
|
||||
const fn = (client as unknown as Record<string, unknown>)[method];
|
||||
if (typeof fn !== 'function') {
|
||||
reject(new Error(`grpc method ${method} not found on the client`));
|
||||
return;
|
||||
}
|
||||
const callback: UnaryCallback<Res> = (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<HubHealth> {
|
||||
const res = await this.unary<Record<string, never>, { 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<string, unknown> {
|
||||
const inputs: Record<string, WirePayload> = {};
|
||||
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<string, PayloadOutput> = {};
|
||||
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<FlowResult> {
|
||||
const res = await this.unary<Record<string, unknown>, 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<FlowEvent, void, void> {
|
||||
const fn = (this.hub as unknown as Record<string, unknown>).submitStream;
|
||||
if (typeof fn !== 'function') throw new Error('grpc method submitStream not found');
|
||||
const call = (fn as (...args: unknown[]) => grpc.ClientReadableStream<unknown>).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<string, unknown>) => {
|
||||
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<void>((resolve) => {
|
||||
wake = resolve;
|
||||
});
|
||||
}
|
||||
} finally {
|
||||
call.cancel();
|
||||
}
|
||||
}
|
||||
|
||||
/** Where a detached run stands. */
|
||||
async getStatus(invocationId: string, deadlineMs?: number): Promise<InvocationStatus> {
|
||||
const res = await this.unary<
|
||||
{ value: string },
|
||||
Partial<InvocationStatus> & { 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<FlowResult> {
|
||||
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<boolean> {
|
||||
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<Approval[]> {
|
||||
const res = await this.unary<
|
||||
{ statuses: string[]; limit: number; project: string },
|
||||
{ entries?: Partial<Approval>[] }
|
||||
>(
|
||||
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<Record<string, unknown>, { 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<string, unknown>): 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<string, PayloadOutput> = {};
|
||||
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;
|
||||
}
|
||||
234
src/errors.ts
Normal file
234
src/errors.ts
Normal file
|
|
@ -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<string> = new Set<ChainErrorKind>([
|
||||
'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<ChainErrorKind, ChainErrorFamily> = {
|
||||
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<ChainErrorFamily> = new Set<ChainErrorFamily>([
|
||||
'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 '<id>'` 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];
|
||||
}
|
||||
668
src/fake_hub.ts
Normal file
668
src/fake_hub.ts
Normal file
|
|
@ -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<string, grpc.status> = {
|
||||
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<string, PayloadInput>;
|
||||
/** 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<string, PayloadInput>;
|
||||
/** 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<string, PayloadOutput>;
|
||||
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<string, PayloadInput>;
|
||||
settle: (outcome: { ok: true; outputs: Record<string, PayloadInput> } | { 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<string, PayloadInput>;
|
||||
}
|
||||
|
||||
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<string, PayloadInput>): Record<string, WirePayload> {
|
||||
const out: Record<string, WirePayload> = {};
|
||||
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<string, RunState>();
|
||||
|
||||
/** Submits blocked on an approval. Dropped by `restart()`. */
|
||||
private waiters = new Map<string, Waiter>();
|
||||
|
||||
/** Idempotency keys this fake has seen, per project. */
|
||||
private keys = new Map<string, string>();
|
||||
|
||||
/** Script the next submit. */
|
||||
push(behaviour: Behaviour): this {
|
||||
this.script.push(behaviour);
|
||||
return this;
|
||||
}
|
||||
|
||||
/** The next submit succeeds with these outputs. */
|
||||
succeeds(outputs: Record<string, PayloadInput> = {}, 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<AwaitApprovalBehaviour, 'type'>): 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<string> {
|
||||
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<number>((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<void> {
|
||||
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<string> {
|
||||
await this.stop();
|
||||
this.runs.clear();
|
||||
return this.start(this.port);
|
||||
}
|
||||
|
||||
/** Shut down for good. */
|
||||
async close(): Promise<void> {
|
||||
await this.stop();
|
||||
this.port = 0;
|
||||
}
|
||||
|
||||
private nextBehaviour(): Behaviour {
|
||||
return this.script.shift() ?? this.fallback;
|
||||
}
|
||||
|
||||
private recordSubmit(call: { request: Record<string, unknown> }, invocationId: string): RecordedSubmit {
|
||||
const request = call.request;
|
||||
const inputs: Record<string, PayloadOutput> = {};
|
||||
for (const [name, payload] of Object.entries(
|
||||
(request.inputs ?? {}) as Record<string, WirePayload>,
|
||||
)) {
|
||||
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<Record<string, unknown>, unknown>, callback: grpc.sendUnaryData<unknown>) => {
|
||||
callback(null, { state: this.health, detail: 'fake hub' });
|
||||
},
|
||||
listModules: (_call: grpc.ServerUnaryCall<Record<string, unknown>, unknown>, callback: grpc.sendUnaryData<unknown>) => {
|
||||
callback(null, { modules: [] });
|
||||
},
|
||||
listInvocations: (_call: grpc.ServerUnaryCall<Record<string, unknown>, unknown>, callback: grpc.sendUnaryData<unknown>) => {
|
||||
callback(null, { invocations: [] });
|
||||
},
|
||||
submit: (call: grpc.ServerUnaryCall<Record<string, unknown>, unknown>, callback: grpc.sendUnaryData<unknown>) => {
|
||||
void this.handleSubmit(call as { request: Record<string, unknown> }, callback);
|
||||
},
|
||||
submitStream: (call: grpc.ServerWritableStream<Record<string, unknown>, unknown>) => {
|
||||
void this.handleSubmitStream(call);
|
||||
},
|
||||
getInvocationStatus: (call: grpc.ServerUnaryCall<Record<string, unknown>, unknown>, callback: grpc.sendUnaryData<unknown>) => {
|
||||
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<Record<string, unknown>, unknown>, callback: grpc.sendUnaryData<unknown>) => {
|
||||
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<Record<string, unknown>, unknown>, callback: grpc.sendUnaryData<unknown>) => {
|
||||
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<string, unknown> },
|
||||
callback: grpc.sendUnaryData<unknown>,
|
||||
): Promise<void> {
|
||||
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<string, PayloadInput>,
|
||||
): Promise<{ ok: true; outputs: Record<string, PayloadInput> } | { 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<Record<string, unknown>, unknown>,
|
||||
): Promise<void> {
|
||||
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<unknown>) => {
|
||||
callback(errorFor('precondition', 'the fake hub does not implement this RPC'));
|
||||
};
|
||||
const handlers: grpc.UntypedServiceImplementation = {
|
||||
listApprovals: (call: grpc.ServerUnaryCall<Record<string, unknown>, unknown>, callback: grpc.sendUnaryData<unknown>) => {
|
||||
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<Record<string, unknown>, unknown>, callback: grpc.sendUnaryData<unknown>) => {
|
||||
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;
|
||||
}
|
||||
}
|
||||
44
src/index.ts
Normal file
44
src/index.ts
Normal file
|
|
@ -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';
|
||||
204
src/payload.ts
Normal file
204
src/payload.ts
Normal file
|
|
@ -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<string, unknown>
|
||||
| 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<string, WireValue>;
|
||||
}
|
||||
|
||||
/** 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<string, unknown>) };
|
||||
}
|
||||
|
||||
/** Convert a plain object into a `google.protobuf.Struct`. */
|
||||
export function structToWire(obj: Record<string, unknown>): WireStruct {
|
||||
const fields: Record<string, WireValue> = {};
|
||||
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<string, unknown> {
|
||||
const out: Record<string, unknown> = {};
|
||||
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<string, unknown>;
|
||||
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<string, unknown>) };
|
||||
}
|
||||
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;
|
||||
}
|
||||
111
src/proto.ts
Normal file
111
src/proto.ts
Normal file
|
|
@ -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<string, grpc.ServiceClientConstructor> };
|
||||
};
|
||||
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;
|
||||
}
|
||||
277
test/client_against_fake.test.ts
Normal file
277
test/client_against_fake.test.ts
Normal file
|
|
@ -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<T>(produce: () => Promise<T | undefined>, timeoutMs = 3_000): Promise<T> {
|
||||
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));
|
||||
}
|
||||
}
|
||||
105
test/errors.test.ts
Normal file
105
test/errors.test.ts
Normal file
|
|
@ -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");
|
||||
});
|
||||
});
|
||||
74
test/payload.test.ts
Normal file
74
test/payload.test.ts
Normal file
|
|
@ -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');
|
||||
});
|
||||
});
|
||||
51
test/proto_copy.test.ts
Normal file
51
test/proto_copy.test.ts
Normal file
|
|
@ -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<string, string>();
|
||||
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`,
|
||||
);
|
||||
}
|
||||
});
|
||||
});
|
||||
127
test/real_hub.test.ts
Normal file
127
test/real_hub.test.ts
Normal file
|
|
@ -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<number> {
|
||||
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}`,
|
||||
);
|
||||
});
|
||||
});
|
||||
21
tsconfig.json
Normal file
21
tsconfig.json
Normal file
|
|
@ -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"]
|
||||
}
|
||||
10
tsconfig.test.json
Normal file
10
tsconfig.test.json
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
{
|
||||
"extends": "./tsconfig.json",
|
||||
"compilerOptions": {
|
||||
"outDir": "build-test",
|
||||
"rootDir": ".",
|
||||
"declaration": false,
|
||||
"declarationMap": false
|
||||
},
|
||||
"include": ["src/**/*.ts", "test/**/*.ts"]
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue