@streamotter/gateway 0.1.0-rc.1 → 0.1.0-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +28 -6
  2. package/package.json +4 -2
package/README.md CHANGED
@@ -1,13 +1,17 @@
1
+ <p align="center"><img src="https://raw.githubusercontent.com/jfricano/StreamOtter/main/docs/assets/streamotter-logo.png" alt="StreamOtter" width="300"></p>
2
+
1
3
  # @streamotter/gateway
2
4
 
3
5
  The StreamOtter Node.js gateway. It consumes Kafka (or deterministic fixtures during development), runs **your** handlers to decide identity, access, public payload, and authoritative state, and delivers state channels to browsers using [`@streamotter/client`](https://www.npmjs.com/package/@streamotter/client). Each subscription gets a snapshot, then full-state updates ordered by revision, with bounded queues and explicit `live`/`stale` states.
4
6
 
5
- > **Release candidate.** `0.1.0-rc.1` is published under the `next` tag. Package versions follow SemVer independently of the V1 protocol and `configVersion: 1`.
7
+ > **Release candidate** of StreamOtter `0.1.0`; the API may still change before `0.1.0`. Package versions follow SemVer independently of the V1 protocol and `configVersion: 1`.
6
8
 
7
9
  ```bash
8
- npm install @streamotter/gateway@next
10
+ npm install @streamotter/gateway
9
11
  ```
10
12
 
13
+ Using the all-in-one [`streamotter`](https://www.npmjs.com/package/streamotter) package instead? Import from `streamotter/gateway`; everything on this page applies unchanged.
14
+
11
15
  Requires Node.js 24 or later. ESM only, with TypeScript declarations included. Kafka access uses KafkaJS 2.2.4 behind an internal adapter. Browser delivery uses Socket.IO 4.8.3 over WebSocket.
12
16
 
13
17
  Most projects run the gateway through [`@streamotter/cli`](https://www.npmjs.com/package/@streamotter/cli) (`streamotter dev` / `streamotter start`), which loads a `streamotter.json` and a handler module. The same pieces work programmatically, as shown below.
@@ -125,6 +129,7 @@ console.log(`StreamOtter listening on ${origin} (${path})`);
125
129
  process.once("SIGTERM", () => void gateway.stop({ timeoutMs: 10_000 }));
126
130
  ```
127
131
 
132
+ - This is an ES module (`"type": "module"` in your `package.json`), because it uses top-level `await`.
128
133
  - `defineProject` validates the configuration synchronously and throws `CONFIG_INVALID` with every issue.
129
134
  - `start()` rolls back and rejects if startup fails or takes longer than 30 seconds. A stopped gateway cannot restart; create a new one.
130
135
  - `mode: "production"` refuses fixture sources, plaintext Kafka, and the `development` option, and requires an exact browser `Origin` on every connection. `mode: "development"` accepts `development: { principals, fixtures }` for local work.
@@ -145,14 +150,31 @@ Revocation takes effect immediately, including while `authorize` or `snapshot` i
145
150
 
146
151
  ## Production boundary
147
152
 
148
- Run **exactly one gateway per project** (V1 has no multi-gateway coordination), behind a TLS-terminating proxy that forwards WebSocket upgrades and the browser's `Origin`. There is no management or health endpoint in production. See [Running StreamOtter](https://github.com/jfricano/StreamOtter/blob/main/docs/DEPLOYMENT.md) for the verified reverse-proxy recipe and the [Kafka support matrix](https://github.com/jfricano/StreamOtter/blob/main/docs/IMPLEMENTATION_STATUS.md#kafka-support-matrix-kafkajs-224--apache-kafka-412): TLS, and TLS with SASL PLAIN and SCRAM-SHA-256/512, are verified against Apache Kafka 4.1.2. Other broker versions and managed services are unverified.
153
+ Run **exactly one gateway per project** (V1 has no multi-gateway coordination), behind a TLS-terminating proxy that forwards WebSocket upgrades and the browser's `Origin`. There is no management or health endpoint in production. See [Run in production](https://github.com/jfricano/StreamOtter/blob/main/docs/DEPLOYMENT.md) for the verified reverse-proxy recipe and the [Kafka support matrix](https://github.com/jfricano/StreamOtter/blob/main/docs/IMPLEMENTATION_STATUS.md#kafka-support-matrix-kafkajs-224--apache-kafka-412): TLS, and TLS with SASL PLAIN and SCRAM-SHA-256/512, are verified against Apache Kafka 4.1.2. Other broker versions and managed services are unverified.
149
154
 
150
155
  `@streamotter/gateway/management` is the development-only management API used by `streamotter dev`; it refuses production gateways. `@streamotter/gateway/internals` exists for StreamOtter's own CLI and is not a stable API.
151
156
 
152
- ## More
157
+ ## Documentation
153
158
 
154
- - [V1 API specification](https://github.com/jfricano/StreamOtter/blob/main/docs/V1_API.md): handlers and lifecycle (§3), synchronization (§5), source progress and limits (§6), access (§7)
159
+ - [Add live state to an existing app](https://github.com/jfricano/StreamOtter/blob/main/docs/guides/existing-app.md): handlers, revisions, the outbox, and revocation, step by step
160
+ - [Connect to Kafka](https://github.com/jfricano/StreamOtter/blob/main/docs/guides/kafka.md): topic shape, TLS and SASL, bad records, crashes, and diagnostics
161
+ - [Run in production](https://github.com/jfricano/StreamOtter/blob/main/docs/DEPLOYMENT.md): `streamotter start`, supervision, and the reverse-proxy recipe
162
+ - [Troubleshooting](https://github.com/jfricano/StreamOtter/blob/main/docs/guides/troubleshooting.md)
163
+ - [V1 API specification](https://github.com/jfricano/StreamOtter/blob/main/docs/V1_API.md): handlers and lifecycle (§3), synchronization (§5), source progress and limits (§6), and access (§7)
155
164
  - [Reference application](https://github.com/jfricano/StreamOtter/tree/main/examples/order-dashboard): fixture and Kafka handlers for a real app
156
- - [Repository](https://github.com/jfricano/StreamOtter) · [Issues](https://github.com/jfricano/StreamOtter/issues)
165
+ - [Repository](https://github.com/jfricano/StreamOtter) · [Issues](https://github.com/jfricano/StreamOtter/issues) · [Security policy](https://github.com/jfricano/StreamOtter/blob/main/SECURITY.md)
166
+
167
+ ## StreamOtter packages
168
+
169
+ | Package | |
170
+ | --- | --- |
171
+ | [`streamotter`](https://www.npmjs.com/package/streamotter) | Everything below in one install, with the `streamotter` command |
172
+ | [`@streamotter/cli`](https://www.npmjs.com/package/@streamotter/cli) | Scaffold, validate, generate types, develop with the workbench, and run the production gateway |
173
+ | [`@streamotter/client`](https://www.npmjs.com/package/@streamotter/client) | The browser SDK: subscribe, render `live` and `stale`, and clean up |
174
+ | [`@streamotter/gateway`](https://www.npmjs.com/package/@streamotter/gateway) | **This package.** Handler types, and running the gateway from your own Node.js code |
175
+ | [`@streamotter/contracts`](https://www.npmjs.com/package/@streamotter/contracts) | Shared types and configuration validation, for tooling authors |
176
+ | [`@streamotter/workbench`](https://www.npmjs.com/package/@streamotter/workbench) | The local workbench's assets, installed by the CLI |
177
+
178
+ All six are released together with the same version ([changelog](https://github.com/jfricano/StreamOtter/blob/main/CHANGELOG.md)).
157
179
 
158
180
  MIT License © 2026 Orca Solutions
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@streamotter/gateway",
3
- "version": "0.1.0-rc.1",
3
+ "version": "0.1.0-rc.3",
4
4
  "description": "StreamOtter Node.js gateway: Kafka and fixture sources, application-owned access handlers, snapshot synchronization, and bounded Socket.IO delivery.",
5
5
  "keywords": [
6
6
  "streamotter",
@@ -26,6 +26,8 @@
26
26
  "license": "MIT",
27
27
  "author": "Orca Solutions",
28
28
  "type": "module",
29
+ "main": "./dist/index.js",
30
+ "types": "./dist/index.d.ts",
29
31
  "exports": {
30
32
  ".": {
31
33
  "types": "./dist/index.d.ts",
@@ -53,7 +55,7 @@
53
55
  "dependencies": {
54
56
  "kafkajs": "2.2.4",
55
57
  "socket.io": "4.8.3",
56
- "@streamotter/contracts": "0.1.0-rc.1"
58
+ "@streamotter/contracts": "0.1.0-rc.3"
57
59
  },
58
60
  "devDependencies": {
59
61
  "@types/node": "24.13.6"