nav/Yonexus
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

add Yonexus.Protocol submodule and update architecture docs

Browse Source
This commit is contained in:
nav
2026-04-01 01:21:47 +00:00
parent 95dc06453a
commit 64dac56e37
6 changed files with 160 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.gitmodules vendored
View File

@@ -4,3 +4,6 @@
[submodule "Yonexus.Client"]
path = Yonexus.Client
url = https://git.hangman-lab.top/nav/Yonexus.Client.git
[submodule "Yonexus.Protocol"]
path = Yonexus.Protocol
url = https://git.hangman-lab.top/nav/Yonexus.Protocol.git

178
ARCHITECTURE.md
View File

@@ -6,13 +6,13 @@ Yonexus is a cross-instance communication system for OpenClaw.
The repository `Yonexus` is the **umbrella/specification repository** for the system. It contains:
- high-level planning
- protocol specification
- shared architectural decisions
- architecture documents
- references to implementation repositories as git submodules
Yonexus is implemented as two separate plugins:
- `Yonexus.Server`
- `Yonexus.Client`
Yonexus is implemented as three repositories:
- `Yonexus.Server` — central hub plugin
- `Yonexus.Client` — client plugin
- `Yonexus.Protocol` — shared protocol specification, referenced as a submodule by both
---
@@ -23,20 +23,34 @@ Yonexus is implemented as two separate plugins:
Purpose:
- system-level planning
- architecture documents
- protocol definition
- shared design decisions
- cross-repo coordination
- cross-cutting decisions that apply to both server and client
- coordination of sub-repositories via git submodules
This repository should contain:
- top-level planning docs
- protocol docs
- feature checklists
- architecture overview
- cross-cutting decisions that apply to both server and client
- feature checklists
- cross-cutting design rationale
This repository should **not** become the place where all implementation code lives.
It references:
- `Yonexus.Server` (submodule)
- `Yonexus.Client` (submodule)
- `Yonexus.Protocol` (submodule)
## 2.2 `Yonexus.Server`
## 2.2 `Yonexus.Protocol`
Purpose:
- protocol specification (PROTOCOL.md)
- canonical JSON shape references
- shared type definitions (planned)
Referenced as a submodule by:
- `Yonexus.Server/protocol`
- `Yonexus.Client/protocol`
This is the **single source of truth** for the Yonexus protocol. Both server and client implementations must conform to the protocol defined here.
## 2.3 `Yonexus.Server`
Purpose:
- implementation of the central hub/server plugin
@@ -44,7 +58,12 @@ Purpose:
- server-side pairing/authentication/state tracking
- server-side dispatch and routing behavior
## 2.3 `Yonexus.Client`
Contains:
- `protocol/` — submodule pointing to `Yonexus.Protocol`
- `PLAN.md`
- implementation code
## 2.4 `Yonexus.Client`
Purpose:
- implementation of the client plugin
@@ -53,9 +72,32 @@ Purpose:
- client-side pairing confirmation and authenticated reconnect
- client-side heartbeat and message sending
Contains:
- `protocol/` — submodule pointing to `Yonexus.Protocol`
- `PLAN.md`
- implementation code
---
## 3. System Topology
## 3. Repository Graph
```
Yonexus (umbrella)
├── Yonexus.Protocol (submodule)
├── Yonexus.Server (submodule)
│ └── protocol/ (nested submodule -> Yonexus.Protocol)
└── Yonexus.Client (submodule)
└── protocol/ (nested submodule -> Yonexus.Protocol)
```
Policy:
- protocol changes are always committed to `Yonexus.Protocol` first
- `Yonexus.Server` and `Yonexus.Client` update their `protocol/` submodule ref after protocol version is stable
- umbrella `Yonexus` updates its submodule refs after server/client have stable versions
---
## 4. System Topology
A Yonexus deployment contains:
- exactly one `Yonexus.Server` instance
@@ -69,7 +111,7 @@ Topology assumptions:
Visual model:
```text
```
Yonexus.Client A --->
\
Yonexus.Client B ----> Yonexus.Server
@@ -79,29 +121,24 @@ Yonexus.Client C --->
---
## 4. Shared vs Split Responsibilities
## 5. Shared vs Split Responsibilities
## 4.1 Shared System Concerns
## 5.1 Yonexus.Protocol — Shared
These belong to the umbrella repo and apply to both plugins:
- protocol format
- builtin message types
These belong to the protocol repo and apply to both plugins:
- protocol format and message categories
- builtin message types and their semantics
- pairing security model
- nonce/timestamp validation rules
- heartbeat timing rules
- message rewrite rules
- reserved rule namespace (`builtin`)
- canonical JSON shapes
- naming and terminology
These should live primarily in:
- `PLAN.md`
- `PROTOCOL.md`
- `FEAT.md`
- `ARCHITECTURE.md`
## 5.2 Server-Only Concerns (Yonexus.Server)
## 4.2 Server-Only Concerns
These belong in `Yonexus.Server` planning/implementation:
These belong in `Yonexus.Server`:
- WebSocket server startup
- listen host/port config
- client registry persistence
@@ -113,9 +150,9 @@ These belong in `Yonexus.Server` planning/implementation:
- client message rewriting and dispatch on server side
- sending messages to connected clients
## 4.3 Client-Only Concerns
## 5.3 Client-Only Concerns (Yonexus.Client)
These belong in `Yonexus.Client` planning/implementation:
These belong in `Yonexus.Client`:
- WebSocket client connection management
- reconnect/backoff logic
- local keypair generation
@@ -128,16 +165,16 @@ These belong in `Yonexus.Client` planning/implementation:
---
## 5. Communication Model
## 6. Communication Model
## 5.1 Transport
## 6.1 Transport
Transport is WebSocket.
- `Yonexus.Server` acts as server
- `Yonexus.Client` acts as client
## 5.2 Message Categories
## 6.2 Message Categories
Two message categories exist on the same transport:
@@ -175,9 +212,9 @@ ${rule_identifier}::${sender_identifier}::${message_content}
---
## 6. Security Architecture
## 7. Security Architecture
## 6.1 Pairing Model
## 7.1 Pairing Model
Pairing is intentionally out-of-band.
@@ -190,7 +227,7 @@ When a new client needs pairing:
This preserves a basic human-mediated trust step.
## 6.2 Post-Pairing Authentication
## 7.2 Post-Pairing Authentication
After pairing:
- server issues a shared secret
@@ -201,7 +238,7 @@ After pairing:
- nonce
- timestamp
## 6.3 Replay Protection
## 7.3 Replay Protection
Server enforces:
- timestamp freshness (`< 10s` drift)
@@ -211,9 +248,9 @@ Server enforces:
---
## 7. State Ownership
## 8. State Ownership
## 7.1 Server-Owned State
## 8.1 Server-Owned State
Canonical server-owned state includes:
- allowed client identifiers
@@ -226,7 +263,7 @@ Canonical server-owned state includes:
- recent handshake attempt window
- client liveness state
## 7.2 Client-Owned State
## 8.2 Client-Owned State
Canonical client-owned state includes:
- client identifier
@@ -237,83 +274,78 @@ Canonical client-owned state includes:
---
## 8. Plugin API Boundaries
## 9. Plugin API Boundaries
## 8.1 Yonexus.Server API
## 9.1 Yonexus.Server API
Planned public API:
- `sendMessageToClient(identifier, message)`
- `registerRule(rule, processor)`
## 8.2 Yonexus.Client API
## 9.2 Yonexus.Client API
Planned public API:
- `sendMessageToServer(message)`
- `registerRule(rule, processor)`
The umbrella repo should define the semantics of these APIs, but implementation details belong in each submodule.
The protocol defines semantics; implementation details belong in each submodule.
---
## 9. Documentation Ownership
## 10. Documentation Ownership
## 9.1 Umbrella Repo Docs
## 10.1 Umbrella Repo Docs
Should contain:
- system architecture
- protocol spec
- cross-cutting feature list
- global design rationale
- cross-repo coordination notes
## 9.2 Server Repo Docs
## 10.2 Protocol Repo Docs
Must contain:
- protocol specification (PROTOCOL.md)
- canonical message shapes
- protocol versioning notes
## 10.3 Server Repo Docs
Should contain:
- server setup
- server config reference
- server persistence model
- server operational behavior
- server implementation tasks
- implementation tasks
## 9.3 Client Repo Docs
## 10.4 Client Repo Docs
Should contain:
- client setup
- client config reference
- client local storage model
- client reconnect/heartbeat behavior
- client implementation tasks
- implementation tasks
---
## 10. Development Flow
## 11. Development Flow
Recommended flow:
1. define cross-cutting behavior in `Yonexus`
2. split actionable work into `Yonexus.Server` and `Yonexus.Client`
3. implement server-side protocol handling in `Yonexus.Server`
4. implement client-side protocol handling in `Yonexus.Client`
5. keep protocol changes synchronized back into umbrella docs
---
## 11. Immediate Next Documents
After this architecture file, the next documents to maintain are:
- `Yonexus.Server/PLAN.md`
- `Yonexus.Client/PLAN.md`
- optionally later:
- `Yonexus.Server/README.md`
- `Yonexus.Client/README.md`
- server/client task breakdown docs
1. define cross-cutting behavior in `Yonexus` umbrella
2. finalize protocol in `Yonexus.Protocol`
3. update submodule refs in `Yonexus.Server` and `Yonexus.Client`
4. implement server-side protocol handling in `Yonexus.Server`
5. implement client-side protocol handling in `Yonexus.Client`
6. keep protocol changes synchronized back into umbrella docs
---
## 12. Non-Goals of the Umbrella Repo
The umbrella repo should avoid becoming:
- the only place where implementation changes happen
- a dumping ground for server-only details
- a dumping ground for client-only details
- the place where all implementation code lives
- a dumping ground for server-only or client-only details
- a duplicate of submodule READMEs without system-level value
Its job is coordination, not code concentration.

85
README.md
View File

@@ -1,11 +1,13 @@
# Yonexus
Yonexus is a cross-instance communication system for OpenClaw built as **two separate plugins**:
Yonexus is a cross-instance communication system for OpenClaw built as **three separate repositories**:
- `Yonexus.Server`
- `Yonexus.Client`
It is designed for scenarios where one OpenClaw instance acts as a central communication hub and multiple other OpenClaw instances connect to it as clients.
| Repository | Role |
|---|---|
| `Yonexus` | Umbrella — architecture, planning, and coordination |
| `Yonexus.Server` | Central hub plugin — accepts client connections, handles pairing/authentication |
| `Yonexus.Client` | Client plugin — connects to server, manages local identity |
| `Yonexus.Protocol` | Shared protocol specification — referenced as a submodule by both Server and Client |
## Overview
@@ -33,6 +35,22 @@ Responsibilities:
- send messages to server
- receive messages from server via rule dispatch
### Yonexus.Protocol
Shared protocol specification repository. Both `Yonexus.Server` and `Yonexus.Client` reference this as a submodule at `protocol/`.
---
## Repository Structure
```
Yonexus (umbrella)
├── Yonexus.Protocol ← shared protocol submodule
├── Yonexus.Server ← server plugin submodule
│ └── protocol/ ← points to Yonexus.Protocol
└── Yonexus.Client ← client plugin submodule
└── protocol/ ← points to Yonexus.Protocol
```
---
## Architecture
@@ -67,48 +85,46 @@ After pairing:
---
## Current Spec Files
This repository currently contains planning/spec-first documents:
## Current Repository Spec Files
### Umbrella (`Yonexus`)
- `PLAN.md` — project plan and architecture
- `PROTOCOL.md` — builtin WebSocket protocol details
- `ARCHITECTURE.md` — architecture overview and repository graph
- `FEAT.md` — implementation feature checklist
---
### Protocol (`Yonexus.Protocol`)
- `PROTOCOL.md` — shared communication protocol specification
## Planned Plugin Manifests
### Server (`Yonexus.Server`)
- `PLAN.md` — server-specific implementation plan
- `protocol/` — submodule pointing to `Yonexus.Protocol`
This repo is expected to define separate plugin manifests for:
- `plugin.server.json`
- `plugin.client.json`
These represent the initial config surface for `Yonexus.Server` and `Yonexus.Client`.
### Client (`Yonexus.Client`)
- `PLAN.md` — client-specific implementation plan
- `protocol/` — submodule pointing to `Yonexus.Protocol`
---
## Planned TypeScript APIs
### Yonexus.Server
- `sendMessageToClient(identifier: string, message: string)`
- `registerRule(rule: string, processor: (message: string) => unknown)`
```ts
sendMessageToClient(identifier: string, message: string): Promise<void>
registerRule(rule: string, processor: (message: string) => unknown): void
```
### Yonexus.Client
- `sendMessageToServer(message: string)`
- `registerRule(rule: string, processor: (message: string) => unknown)`
```ts
sendMessageToServer(message: string): Promise<void>
registerRule(rule: string, processor: (message: string) => unknown): void
```
Message format:
```text
${rule_identifier}::${message_content}
```
Reserved rule:
```text
builtin
```
Reserved rule: `builtin`
---
@@ -140,19 +156,16 @@ builtin
## Status
Current repository status:
- planning/specification stage
- split-plugin architecture defined
- protocol draft defined
- protocol draft defined in `Yonexus.Protocol`
- implementation not started yet
---
## Next Steps
## Repository URLs
Recommended next deliverables:
- plugin manifests
- source tree scaffolds for server/client
- protocol model types
- transport skeleton
- pairing/auth flow implementation
- [Yonexus (umbrella)](https://git.hangman-lab.top/nav/Yonexus)
- [Yonexus.Server](https://git.hangman-lab.top/nav/Yonexus.Server)
- [Yonexus.Client](https://git.hangman-lab.top/nav/Yonexus.Client)
- [Yonexus.Protocol](https://git.hangman-lab.top/nav/Yonexus.Protocol)

2
Yonexus.Client

Submodule Yonexus.Client updated: c5330bb9f9...183f2eea6d

1
Yonexus.Protocol Submodule

Submodule Yonexus.Protocol added at 9232aa7c17

2
Yonexus.Server

Submodule Yonexus.Server updated: 23969afa80...871fe94318