@agntcy/slim-bindings 1.0.0 → 1.4.0-rc.2

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 +37 -74
  2. package/package.json +10 -10
package/README.md CHANGED
@@ -1,107 +1,70 @@
1
- # SLIM JavaScript / TypeScript bindings (`@agntcy/slim-bindings`)
1
+ # `@agntcy/slim-bindings`
2
2
 
3
- This is thenpm package for using SLIM from JavaScript and TypeScript. It targets **Node.js** (≥18): servers, services, CLIs, tests, and any workflow where the native addon loads through Node.
3
+ Node.js (≥18) bindings for **SLIM**: connect apps to a SLIM server, open sessions, and exchange messages using the same Rust core as other language bindings.
4
4
 
5
- Bindings are generated with [uniffi-bindgen-node](https://github.com/livekit/uniffi-bindgen-node) and talk to the Rust core via [ffi-rs](https://www.npmjs.com/package/ffi-rs).
6
-
7
- ## Features
8
-
9
- - **Primary JS/TS entry point** — Install `@agntcy/slim-bindings` for Node; optional `@agntcy/slim-bindings-*` packages supply the correct native binary per OS/arch.
10
- - **Rust-backed core** — Same SLIM logic as other language bindings; native code ships per platform.
11
- - **TypeScript** — Typed surface and editor support (with known FFI quirks documented below).
12
- - **Authentication** — Shared secret, JWT, and SPIRE-oriented flows exposed through the generated API.
13
- - **Async-first** — Promise-based calls aligned with Node conventions.
14
- - **UniFFI** — Generated from Mozilla’s [UniFFI](https://mozilla.github.io/uniffi-rs/) bindings.
15
-
16
- ## Installation
17
-
18
- Published builds install from npm only (no local Rust required):
5
+ ## Install
19
6
 
20
7
  ```bash
21
8
  npm install @agntcy/slim-bindings
22
9
  ```
23
10
 
24
- That pulls this package plus the matching optional native addon for your platform when a release exists for your version.
11
+ npm installs this package and, when published for your OS/arch, the matching optional native addon (`@agntcy/slim-bindings-*`). If install fails with a native-load error, your platform/version combo may not have a published binary yet.
25
12
 
26
- To build from source (development or an unpublished platform), see [Build from source](#build-from-source).
13
+ ## Module shape
27
14
 
28
- ## Prerequisites (build from source)
15
+ The published entry loads the generated UniFFI/Node bindings (see `package.json` `main` / `types`). From TypeScript or ESM-aware tooling you typically import the default export from the package path your bundler resolves (examples in this repo import from `generated/slim-bindings-node.js` when running inside the bindings workspace).
29
16
 
30
- - Rust toolchain
31
- - Node.js >= 18
32
- - [Task](https://taskfile.dev/)
17
+ ```typescript
18
+ import slimBindings from '@agntcy/slim-bindings';
33
19
 
34
- ## Usage
20
+ slimBindings.initializeWithDefaults();
21
+ const service = slimBindings.getGlobalService();
22
+ ```
35
23
 
36
- ### 1. Generate bindings (from source)
24
+ Full TypeScript types ship under `types/` in the published package (`index.d.ts` re-exports them).
37
25
 
38
- ```bash
39
- task generate
40
- ```
26
+ ## Typical flow
41
27
 
42
- ### 2. Run P2P examples
28
+ 1. **Initialize** crypto/runtime once per process:
43
29
 
44
- ```bash
45
- # Terminal 1: Start the server
46
- task example:server
30
+ `slimBindings.initializeWithDefaults()`
47
31
 
48
- # Terminal 2: Start Alice (receiver)
49
- task example:alice
32
+ 2. **Obtain the global service** — entry point for apps, connections, and server mode:
50
33
 
51
- # Terminal 3: Start Bob (sender)
52
- task example:bob
53
- ```
34
+ `slimBindings.getGlobalService()`
54
35
 
55
- ### Available commands
36
+ 3. **Identity** — SLIM names are three segments: `organization/namespace/application` (constructor `new slimBindings.Name(org, ns, app)`).
56
37
 
57
- ```bash
58
- task generate # Generate bindings
59
- task clean # Clean build artifacts
60
- task example:server # Run server
61
- task example:alice # Run Alice receiver
62
- task example:bob # Run Bob sender
63
- ```
38
+ 4. **Client: create an app** — e.g. shared-secret auth:
64
39
 
65
- ## Build process
40
+ `service.createAppWithSecret(name, secret)`
41
+ Use a secret that meets the minimum length required by your deployment (examples use a 32+ character demo string).
66
42
 
67
- Generation applies small patches so output from `uniffi-bindgen-node` works with the shared `uniffi-bindgen-react-native` runtime dependency:
43
+ 5. **Client: connect to the SLIM server** — build a client config (see `newInsecureClientConfig(url)` for development-style HTTP to the server), then:
68
44
 
69
- - **Naming**: `FfiConverterBytes` → `FfiConverterArrayBuffer`
70
- - **Buffers**: Correct RustBuffer handling for byte arrays
71
- - **Pointers**: BigInt ↔ Number at FFI boundaries where needed
72
- - **Errors**: Clearer extraction from Rust error types
45
+ `await service.connectAsync(config)`
46
+ Returns a connection id used for routing/subscriptions.
73
47
 
74
- ## FFI type conversions
48
+ 6. **Subscribe** the app to receive traffic for its name (often passing `BigInt(connId)` if the generated API expects `bigint` — see note below).
75
49
 
76
- Generated TypeScript may use `bigint` for some unsigned 64-bit values while the FFI layer returns JavaScript `number` at runtime. Normalize at your API boundary:
50
+ 7. **Server** — for a network node that accepts clients, initialize the same way, then build a server config (e.g. `newInsecureServerConfig('0.0.0.0:46357')`) and run:
77
51
 
78
- ```typescript
79
- const connId = await service.connectAsync(config);
80
- await app.subscribeAsync(name, BigInt(connId));
81
- app.setRoute(name, Number(connId));
82
- ```
52
+ `slimBindings.getGlobalService().runServer(config)`
53
+ The process must stay alive while the server runs (see examples).
83
54
 
84
- - `connectAsync` often behaves like `number` at runtime → use `BigInt()` when a parameter expects `bigint`.
85
- - When calling through to FFI with u64 parameters → use `Number()` from `bigint` when required.
55
+ ## Examples
86
56
 
87
- ## Build from source
57
+ Runnable scripts live under `examples/` (from repo root, use the `Taskfile` targets `example:server`, `example:alice`, `example:bob`, or run them via npm from `examples/` as documented in [README_dev.md](./README_dev.md)).
88
58
 
89
- 1. Install Rust and Task.
90
- 2. Run `task generate` (builds the Rust library and emits Node bindings).
91
- 3. Consume files under `generated/` or run examples (`task example:server`, etc.).
59
+ ## `bigint` vs `number` (FFI)
92
60
 
93
- Optional platform packages (`@agntcy/slim-bindings-*`) are version-pinned beside this package in `package.json`. For a **local** platform tarball from `task pack:platform`, install it explicitly (for example `npm install ./dist/node-darwin-arm64.tgz`) in addition to this package.
61
+ Some APIs are typed with `bigint` for 64-bit values, but `connectAsync` may return a JavaScript `number` at runtime. When you pass that value into a method that expects `bigint` (for example `subscribeAsync`), wrap it: `BigInt(connId)`. See [README_dev.md](./README_dev.md#ffi-type-conversions) for details.
94
62
 
95
- ## Publishing (maintainers)
63
+ ## Building from source / contributing
96
64
 
97
- - **Dry run**: From `data-plane/bindings/node`, run `npm pack` for the main tarball; platform bundles via `task pack:platform TARGET=<target>` → `dist/node-<platform>.tgz`.
98
- - **Version**: In `package.json`; release tags use `slim-bindings-v*` (see `.github/scripts/get-binding-version.sh`).
99
- - **Secrets**: `NPM_TOKEN` for `npm publish`.
65
+ Generator setup, Task commands, publishing, and FFI patches are documented for maintainers in **[README_dev.md](./README_dev.md)**.
100
66
 
101
- ## Resources
67
+ ## Links
102
68
 
103
- - [uniffi-bindgen-node](https://github.com/livekit/uniffi-bindgen-node)
104
- - [UniFFI](https://mozilla.github.io/uniffi-rs/)
105
- - [ffi-rs](https://www.npmjs.com/package/ffi-rs)
106
- - [SLIM](https://github.com/agntcy/slim)
107
- - [React Native bindings](../react-native/README.md)
69
+ - [SLIM repository](https://github.com/agntcy/slim)
70
+ - [React Native bindings](../react-native/README.md) (mobile / JSI)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agntcy/slim-bindings",
3
- "version": "1.0.0",
3
+ "version": "1.4.0-rc.2",
4
4
  "description": "SLIM Node.js bindings using UniFFI",
5
5
  "main": "index.js",
6
6
  "types": "index.d.ts",
@@ -35,15 +35,15 @@
35
35
  },
36
36
  "license": "Apache-2.0",
37
37
  "optionalDependencies": {
38
- "@agntcy/slim-bindings-darwin-arm64": "1.0.0",
39
- "@agntcy/slim-bindings-darwin-x64": "1.0.0",
40
- "@agntcy/slim-bindings-linux-arm64-gnu": "1.0.0",
41
- "@agntcy/slim-bindings-linux-arm64-musl": "1.0.0",
42
- "@agntcy/slim-bindings-linux-x64-gnu": "1.0.0",
43
- "@agntcy/slim-bindings-linux-x64-musl": "1.0.0",
44
- "@agntcy/slim-bindings-win32-arm64-msvc": "1.0.0",
45
- "@agntcy/slim-bindings-win32-x64-gnu": "1.0.0",
46
- "@agntcy/slim-bindings-win32-x64-msvc": "1.0.0"
38
+ "@agntcy/slim-bindings-darwin-arm64": "1.4.0-rc.2",
39
+ "@agntcy/slim-bindings-darwin-x64": "1.4.0-rc.2",
40
+ "@agntcy/slim-bindings-linux-arm64-gnu": "1.4.0-rc.2",
41
+ "@agntcy/slim-bindings-linux-arm64-musl": "1.4.0-rc.2",
42
+ "@agntcy/slim-bindings-linux-x64-gnu": "1.4.0-rc.2",
43
+ "@agntcy/slim-bindings-linux-x64-musl": "1.4.0-rc.2",
44
+ "@agntcy/slim-bindings-win32-arm64-msvc": "1.4.0-rc.2",
45
+ "@agntcy/slim-bindings-win32-x64-gnu": "1.4.0-rc.2",
46
+ "@agntcy/slim-bindings-win32-x64-msvc": "1.4.0-rc.2"
47
47
  },
48
48
  "devDependencies": {
49
49
  "@types/node": "^20.0.0",