docs: expand SDK README
This commit is contained in:
Ubuntu
parent
661d01ff1e
commit
00b9099be1
200
README.md
200
README.md
@ -1,22 +1,192 @@
|
||||
# Matrix SDK Workspace
|
||||
# Matrix SDK
|
||||
|
||||
This workspace is the isolated SDK incubation area for
|
||||
`WORKSTREAMS/matrix-sdk-isolation`.
|
||||
Matrix SDK is the package-author layer for building Matrix actors, browser
|
||||
surfaces, and broker-connected applications without depending on the HiveCast
|
||||
platform repo.
|
||||
|
||||
Current proven checkpoints:
|
||||
This repository contains the SDK packages that were split out of Matrix-3 and
|
||||
renamed to their publishable `@open-matrix/*` package names. The split is
|
||||
proven as a standalone workspace: a fresh clone can install, build, test,
|
||||
type-check, pack every package, and compile an external consumer against the
|
||||
packed tarballs.
|
||||
|
||||
- copied SDK-bearing packages build/test/type-check/pack independently
|
||||
- copied package identities were renamed to final `@open-matrix/*` names
|
||||
- `@open-matrix/sdk` facade package builds/tests/packs
|
||||
- `@open-matrix/browser-kit` builds package-manager-ready `dist` exports
|
||||
- a fresh external temp consumer installs packed tarballs, compiles, starts a
|
||||
`MatrixActor`, and calls it through the Matrix runtime/transport path
|
||||
## What You Can Build
|
||||
|
||||
Proof commands:
|
||||
- Headless actors with `MatrixActor`
|
||||
- Browser custom elements with `MatrixActorHtmlElement`
|
||||
- In-memory actor graphs for tests and local development
|
||||
- NATS-backed transports for broker-connected actors
|
||||
- Browser host integrations for Matrix web surfaces
|
||||
- Package-author CLIs and project scaffolds
|
||||
|
||||
```bash
|
||||
pnpm --dir projects/matrix-sdk prove
|
||||
pnpm --dir projects/matrix-sdk prove:external-consumer
|
||||
Matrix SDK is provider-neutral. It does not require HiveCast, Device Link, Host
|
||||
Link, Host Service, or a local HiveCast install. HiveCast is one managed provider
|
||||
that can issue broker credentials and host runtimes on top of the SDK.
|
||||
|
||||
## Packages
|
||||
|
||||
| Package | Purpose |
|
||||
| --- | --- |
|
||||
| `@open-matrix/sdk` | Public umbrella facade for actor/package authors |
|
||||
| `@open-matrix/core` | Actor kernel, runtime, transports, serialization, browser actor base classes |
|
||||
| `@open-matrix/cli` | Package-author `matrix` CLI |
|
||||
| `@open-matrix/browser-kit` | Browser app shims, theme tokens, Vite helpers, shell components |
|
||||
| `@open-matrix/browser-host` | Browser runtime host shell and app-ready integration |
|
||||
| `@open-matrix/contracts` | Shared type contracts for placement, service registry, and runtime presence |
|
||||
| `@open-matrix/federation` | Cross-realm messaging, MX envelope handling, and routing helpers |
|
||||
| `@open-matrix/omega-core` | Narrow Omega interpreter facade used by Matrix membranes |
|
||||
|
||||
Prefer narrow imports when possible:
|
||||
|
||||
```ts
|
||||
import { MatrixActor } from '@open-matrix/core';
|
||||
```
|
||||
|
||||
Matrix-3 consumers have not been repointed yet.
|
||||
Use the umbrella package when you intentionally want the public SDK facade:
|
||||
|
||||
```ts
|
||||
import { MatrixActor } from '@open-matrix/sdk';
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
git clone git@github.com:matrix-sdk/matrix-sdk.git
|
||||
cd matrix-sdk
|
||||
pnpm install --frozen-lockfile
|
||||
pnpm prove
|
||||
```
|
||||
|
||||
`pnpm prove` runs the standalone proof:
|
||||
|
||||
```text
|
||||
clean -> build -> test -> type-check -> pack all packages
|
||||
```
|
||||
|
||||
For the external-consumer proof:
|
||||
|
||||
```bash
|
||||
pnpm prove:external-consumer
|
||||
```
|
||||
|
||||
That proof packs the SDK packages, creates a temporary consumer outside this
|
||||
repo, installs the packed tarballs, compiles TypeScript, starts a `MatrixActor`,
|
||||
and calls it through the Matrix runtime/transport path.
|
||||
|
||||
## Minimal Actor
|
||||
|
||||
```ts
|
||||
import {
|
||||
InMemoryBroker,
|
||||
InMemoryTransport,
|
||||
MatrixActor,
|
||||
MatrixRuntime,
|
||||
TopicRouter,
|
||||
} from '@open-matrix/core';
|
||||
|
||||
class EchoActor extends MatrixActor {
|
||||
static accepts = {
|
||||
echo: {},
|
||||
};
|
||||
|
||||
onEcho(payload: { message?: string }) {
|
||||
return {
|
||||
ok: true,
|
||||
message: payload.message ?? null,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
const broker = new InMemoryBroker();
|
||||
const transport = new InMemoryTransport(broker, { name: 'demo' });
|
||||
const runtime = new MatrixRuntime({ transport, logging: false });
|
||||
|
||||
await runtime.create(EchoActor, 'demo.echo');
|
||||
|
||||
const replyTo = '$replies.demo';
|
||||
const response = new Promise((resolve) => {
|
||||
const unsubscribe = transport.subscribe(replyTo, (value) => {
|
||||
unsubscribe();
|
||||
resolve(value);
|
||||
});
|
||||
});
|
||||
|
||||
transport.publish(TopicRouter.inbox('demo.echo'), {
|
||||
op: 'echo',
|
||||
payload: { message: 'hello' },
|
||||
replyTo,
|
||||
correlationId: 'demo-1',
|
||||
});
|
||||
|
||||
console.log(await response);
|
||||
await runtime.shutdown();
|
||||
```
|
||||
|
||||
## CLI
|
||||
|
||||
The SDK CLI package owns the package-author `matrix` binary.
|
||||
|
||||
```bash
|
||||
matrix init [dir]
|
||||
matrix add actor <name>
|
||||
matrix actor <name>
|
||||
matrix configure --key <key> --cloud <url> --space <space>
|
||||
matrix run <entry> --mount <mount>
|
||||
matrix invoke <mount> <op> [json]
|
||||
```
|
||||
|
||||
The current CLI proof is:
|
||||
|
||||
```bash
|
||||
pnpm prove:cli-uat
|
||||
```
|
||||
|
||||
The CLI is intended to let a package author initialize a folder, add actors,
|
||||
configure broker access, run actors, and invoke them without importing HiveCast
|
||||
product packages into the SDK layer.
|
||||
|
||||
## Repository Layout
|
||||
|
||||
```text
|
||||
packages/
|
||||
browser-host/
|
||||
browser-kit/
|
||||
cli/
|
||||
contracts/
|
||||
core/
|
||||
federation/
|
||||
omega-core/
|
||||
sdk/
|
||||
scripts/
|
||||
prove-external-consumer.mjs
|
||||
prove-sdk-cli-uat.mjs
|
||||
```
|
||||
|
||||
## Current Status
|
||||
|
||||
Done and proven:
|
||||
|
||||
- The SDK packages build independently from Matrix-3.
|
||||
- Package identities use final `@open-matrix/*` names.
|
||||
- `@open-matrix/sdk` re-exports the public actor facade.
|
||||
- A fresh clone passes `pnpm install --frozen-lockfile && pnpm prove`.
|
||||
- A temporary external consumer can install packed SDK tarballs, compile, start
|
||||
a `MatrixActor`, and call it through Matrix runtime/transport.
|
||||
|
||||
Still planned:
|
||||
|
||||
- Provider-neutral credential resolution for `matrix configure` and SDK users.
|
||||
- `matrix login --provider hivecast` to write the same config shape as
|
||||
`matrix configure`.
|
||||
- Direct broker mode with explicit broker URL/JWT/seed credentials.
|
||||
- HiveCast provider mode where HiveCast issues scoped broker credentials.
|
||||
- Publishing the packages to npm after the provider-login contract is complete.
|
||||
|
||||
## Relationship To HiveCast
|
||||
|
||||
Matrix SDK is the open, provider-neutral actor SDK.
|
||||
|
||||
HiveCast is a managed overlay on top of Matrix SDK. HiveCast can provide account
|
||||
management, Spaces, API keys, broker credential issuance, runtime hosting,
|
||||
package distribution, and operator UI. SDK users should still be able to connect
|
||||
to another broker directly when they already manage their own broker credentials.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user