From 4444a8c0bfebc539e617abbb4ebc57fcf837b479 Mon Sep 17 00:00:00 2001 From: ruby Date: Fri, 9 Oct 2026 09:14:42 +0200 Subject: [PATCH] Add the README for the TypeScript Nexus client. --- README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..9e324e3 --- /dev/null +++ b/README.md @@ -0,0 +1,44 @@ +[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) +[![Node.js](https://img.shields.io/badge/Node.js-LTS-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/) +[![gRPC](https://img.shields.io/badge/gRPC-%40grpc%2Fgrpc--js-244C5A?logo=grpc)](https://grpc.io/docs/languages/node/) +[![protobuf](https://img.shields.io/badge/protobuf-ts--proto-4285F4?logo=protobuf&logoColor=white)](https://protobuf.dev/) + +# mishima-nexus-client-typescript + +Node.js client, written in TypeScript, for a remote [Mishima Nexus](https://brokkr.robotico.dev/mishima/mishima-nexus) server. It speaks gRPC `mishima.nexus.v1` (`proto/mishima/nexus/v1` in `mishima-nexus`). It does not embed the engines and it does not call `Mishima.Nexus.Node.*`. + +- Brokkr: `https://brokkr.robotico.dev/mishima/mishima-nexus-client-typescript` + +This is the data-plane client for a Node.js API. A browser app does not use it. Browser consoles call the Admin REST BFF with OIDC. + +Stubs are generated with `@grpc/grpc-js` and `ts-proto` and are not edited by hand. The hand-written layer parses the connection URI, loads TLS material, attaches auth metadata, and maps `NexusStatus` to a typed error. + +## Connection URIs + +| Scheme | Plane | Default database (empty path) | +|---|---|---| +| `nexus+graph://` | Graph | `pathways` | +| `nexus+time://` | Time | `telemetry` | +| `nexus+document://` | Document | `catalog` | +| `nexus+relational://` | Relational | `ledger` | +| `nexus+vector://` | Vector | path segment | +| `nexus+sql://` | — | rejected — not this client's wire | + +The URI **host:port** is the gRPC endpoint. The port is always explicit. The URI **path** (for example `/pathways`) is the logical database name, sent as the `x-nexus-database` gRPC metadata header on every call. One client is bound to a single scheme and logical database. Open a second client for another plane or database. + +## TLS / mTLS / bearer auth + +| Variable | Purpose | +|---|---| +| `NEXUS_TLS_CA_FILE` | CA certificate PEM (trust root) | +| `NEXUS_TLS_CLIENT_CERT_FILE` | Client (machine credential) certificate | +| `NEXUS_TLS_CLIENT_KEY_FILE` | Client private key PEM | +| `NEXUS_TLS_MODE` | `https` (default) or `insecure` | +| `NEXUS_WIRE_BEARER` | Bearer token attached as `Authorization` | +| `NEXUS_WIRE_DEFAULT_BEARER` | Fallback bearer token | + +A backend uses a machine credential (mTLS, optional service JWT). When no TLS material is present and HTTPS is unset, the client dials plaintext h2c for loopback development only. + +## Errors + +Wire failures surface as stable `NXS_*` codes: `NXS_URI_INVALID`, `NXS_URI_UNSUPPORTED_SCHEME`, `NXS_CONNECT_FAILED`, `NXS_TLS_REJECTED`, `NXS_ALREADY_EXISTS`, `NXS_NOT_FOUND`, `NXS_INVALID_ARGUMENT`, `NXS_DISPOSED`, `NXS_UNAVAILABLE`, `NXS_WIRE_FAILED`.