42 lines
2.5 KiB
Markdown
42 lines
2.5 KiB
Markdown
[](https://www.ruby-lang.org/)
|
|
[](https://grpc.io/docs/languages/ruby/)
|
|
[](https://protobuf.dev/)
|
|
|
|
# mishima-nexus-client-ruby
|
|
|
|
Ruby client 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 link `Mishima.Nexus.Node.*`. A Rails application uses this client; it does not get a separate wire.
|
|
|
|
- Brokkr: `https://brokkr.robotico.dev/mishima/mishima-nexus-client-ruby`
|
|
|
|
Stubs are generated with the `grpc` gem and are not edited by hand. The hand-written layer parses the connection URI, loads TLS material, attaches auth metadata, and maps `NexusStatus` to an exception.
|
|
|
|
## 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`.
|