vortez-io 1.0.2 → 2.0.0
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.
- package/README.md +4 -0
- package/build/Frame.js +1 -1
- package/build/RequestManager.d.ts +15 -14
- package/build/RequestManager.js +6 -0
- package/build/RequestManager.js.map +1 -1
- package/build/VIO.d.ts +133 -11
- package/build/VIO.js +105 -4
- package/build/VIO.js.map +1 -1
- package/build/VIOError.d.ts +6 -0
- package/build/VIOError.js +6 -0
- package/build/VIOError.js.map +1 -1
- package/build/index.d.ts +2 -1
- package/build/index.js +1 -1
- package/build/index.js.map +1 -1
- package/build/strict/VIOStrict.d.ts +57 -0
- package/build/strict/VIOStrict.js +56 -0
- package/build/strict/VIOStrict.js.map +1 -0
- package/build/strict/channel/Channel.d.ts +34 -0
- package/build/strict/channel/Channel.js +16 -0
- package/build/strict/channel/Channel.js.map +1 -0
- package/build/strict/channel/EventChannel.d.ts +53 -0
- package/build/strict/channel/EventChannel.js +58 -0
- package/build/strict/channel/EventChannel.js.map +1 -0
- package/build/strict/channel/RequestChannel.d.ts +67 -0
- package/build/strict/channel/RequestChannel.js +96 -0
- package/build/strict/channel/RequestChannel.js.map +1 -0
- package/build/strict/channel/TransportChannel.d.ts +38 -0
- package/build/strict/channel/TransportChannel.js +30 -0
- package/build/strict/channel/TransportChannel.js.map +1 -0
- package/build/support/Isomorphic.d.ts +18 -0
- package/build/support/Isomorphic.js +2 -0
- package/build/support/Isomorphic.js.map +1 -0
- package/build/support/LineParser.js +2 -4
- package/build/support/LineParser.js.map +1 -1
- package/build/support/UTF8Codec.d.ts +2 -7
- package/build/support/UTF8Codec.js +2 -7
- package/build/support/UTF8Codec.js.map +1 -1
- package/build/support/UUID.d.ts +1 -1
- package/build/support/UUID.js +1 -1
- package/build/support/Varint.js +2 -4
- package/build/support/Varint.js.map +1 -1
- package/docs/ARCHITECTURE.md +200 -0
- package/package.json +1 -1
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"UTF8Codec.js","sourceRoot":"","sources":["../../src/support/UTF8Codec.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"UTF8Codec.js","sourceRoot":"","sources":["../../src/support/UTF8Codec.ts"],"names":[],"mappings":"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"}
|
package/build/support/UUID.d.ts
CHANGED
package/build/support/UUID.js
CHANGED
package/build/support/Varint.js
CHANGED
|
@@ -1,10 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* @module vortez-io
|
|
3
|
-
* @author NetFeez <netfeez.dev@
|
|
3
|
+
* @author NetFeez <netfeez.dev@gmail.com>
|
|
4
4
|
* @license Apache-2.0
|
|
5
|
-
* @description
|
|
6
|
-
* Varints are a compact way to encode integers, where smaller numbers take fewer bytes. Each byte uses the lower 7 bits to store data and the highest bit as a continuation flag (1 if more bytes follow, 0 if this is the last byte).
|
|
7
|
-
* This module includes methods for reading varints from a Uint8Array and writing numbers as varints into a Uint8Array, with error handling for invalid input and buffer overflows.
|
|
5
|
+
* @description Varint read and write helpers for the Vortez IO protocol.
|
|
8
6
|
*/
|
|
9
7
|
import VIOError from "../VIOError.js";
|
|
10
8
|
export class Varint {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Varint.js","sourceRoot":"","sources":["../../src/support/Varint.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"Varint.js","sourceRoot":"","sources":["../../src/support/Varint.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAEtC,MAAM,OAAO,MAAM;IACf;;;;;;;OAOG;IACI,MAAM,CAAC,UAAU,CAAC,IAAgB,EAAE,MAAc;QACrD,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,GAAG,GAAG,MAAM,CAAC;QAEjB,OAAO,IAAI,EAAE,CAAC;YACV,IAAI,GAAG,IAAI,IAAI,CAAC,MAAM;gBAAE,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAC;YAC/F,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;YACzB,KAAK,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,CAAC;YAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC;gBAAE,MAAM;YAC/B,KAAK,IAAI,CAAC,CAAC;YACX,IAAI,KAAK,GAAG,EAAE;gBAAE,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,kBAAkB,CAAC,CAAC;QACvF,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IAClC,CAAC;IACD;;;;;;OAMG;IACI,MAAM,CAAC,WAAW,CAAC,KAAa;QACnC,IAAI,KAAK,GAAG,CAAC;YAAE,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,2BAA2B,CAAC,CAAC;QAC3F,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,OAAO,IAAI,EAAE,CAAC;YACV,IAAI,IAAI,GAAG,KAAK,GAAG,IAAI,CAAC;YACxB,KAAK,MAAM,CAAC,CAAC;YACb,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;gBAAC,IAAI,IAAI,IAAI,CAAC;YAAC,CAAC;YAClC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,IAAI,KAAK,KAAK,CAAC;gBAAE,MAAM;QAC3B,CAAC;QACD,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;CACJ;AAOD,eAAe,MAAM,CAAC"}
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# Vortez IO Architecture Guide
|
|
2
|
+
|
|
3
|
+
This document explains how Vortez IO works internally, how protocol frames move through the runtime end to end, and how the public API layers fit together.
|
|
4
|
+
|
|
5
|
+
## Who This Is For
|
|
6
|
+
|
|
7
|
+
- Engineers evaluating Vortez IO for WebSocket-based messaging.
|
|
8
|
+
- Teams integrating request/response correlation or event delivery.
|
|
9
|
+
- Contributors who need to understand the runtime boundaries and extension points.
|
|
10
|
+
|
|
11
|
+
## System At A Glance
|
|
12
|
+
|
|
13
|
+
```mermaid
|
|
14
|
+
flowchart TD
|
|
15
|
+
A[Application Code] --> B[VIO]
|
|
16
|
+
B --> C[Frame Encoder / Decoder]
|
|
17
|
+
B --> D[RequestManager]
|
|
18
|
+
B --> E[Transport Emitter]
|
|
19
|
+
B --> F[Event Handlers]
|
|
20
|
+
D --> G[UUID Correlation]
|
|
21
|
+
E --> H[WebSocket Transport]
|
|
22
|
+
H --> I[Remote Peer]
|
|
23
|
+
B --> J[VIOStrict]
|
|
24
|
+
J --> K[EventChannel]
|
|
25
|
+
J --> L[RequestChannel]
|
|
26
|
+
J --> M[TransportChannel]
|
|
27
|
+
K --> N[Schema Validation]
|
|
28
|
+
L --> N
|
|
29
|
+
M --> E
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Runtime Layers
|
|
33
|
+
|
|
34
|
+
Vortez IO is intentionally split into a small set of layers:
|
|
35
|
+
|
|
36
|
+
- `Frame` owns binary protocol encoding and decoding.
|
|
37
|
+
- `VIO` owns transport-facing behavior and dispatches incoming frames.
|
|
38
|
+
- `RequestManager` tracks pending requests, UUID correlation, and timeouts.
|
|
39
|
+
- `VIOStrict` wraps `VIO` with typed channels and schema validation.
|
|
40
|
+
- Support modules provide UTF-8, varint, UUID, and line-based codecs.
|
|
41
|
+
|
|
42
|
+
This keeps binary protocol concerns isolated from typed application concerns.
|
|
43
|
+
|
|
44
|
+
## Frame Lifecycle
|
|
45
|
+
|
|
46
|
+
```mermaid
|
|
47
|
+
flowchart TD
|
|
48
|
+
A[Application payload] --> B[VIO.request / VIO.event / VIO.raw]
|
|
49
|
+
B --> C[serialize]
|
|
50
|
+
C --> D[Frame.encode]
|
|
51
|
+
D --> E[Transport send event]
|
|
52
|
+
E --> F[WebSocket send]
|
|
53
|
+
F --> G[Remote side receives bytes]
|
|
54
|
+
G --> H[Frame.decode]
|
|
55
|
+
H --> I[VIO.handle]
|
|
56
|
+
I --> J{Frame type}
|
|
57
|
+
J -->|EVENT| K[handleEvent]
|
|
58
|
+
J -->|REQUEST| L[handleRequest]
|
|
59
|
+
J -->|RESPONSE| M[handleResponse]
|
|
60
|
+
J -->|ERROR| N[handleError]
|
|
61
|
+
J -->|RAW| O[handleRaw]
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Key behavior
|
|
65
|
+
|
|
66
|
+
- `Frame` always expects the protocol header to be present.
|
|
67
|
+
- `REQUEST` and `RESPONSE` frames use UUID identifiers.
|
|
68
|
+
- `EVENT` frames use string identifiers.
|
|
69
|
+
- `ERROR` frames can be protocol-level (`NONE`) or request-bound (`UUID`).
|
|
70
|
+
- `RAW` frames are passed through without higher-level interpretation.
|
|
71
|
+
|
|
72
|
+
## Request Lifecycle
|
|
73
|
+
|
|
74
|
+
```mermaid
|
|
75
|
+
flowchart TD
|
|
76
|
+
A["Application calls request()"] --> B[RequestManager.send]
|
|
77
|
+
B --> C[Generate UUID]
|
|
78
|
+
C --> D[Store pending promise]
|
|
79
|
+
D --> E[Emit send event]
|
|
80
|
+
E --> F[VIO.sendRequest]
|
|
81
|
+
F --> G[Frame.encode REQUEST]
|
|
82
|
+
G --> H[Remote peer processes frame]
|
|
83
|
+
H --> I[Response or ERROR returned]
|
|
84
|
+
I --> J[VIO.handleResponse / VIO.handleError]
|
|
85
|
+
J --> K[RequestManager.handle]
|
|
86
|
+
K --> L[Resolve or reject promise]
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### Key behavior
|
|
90
|
+
|
|
91
|
+
- Request correlation is handled entirely by UUID.
|
|
92
|
+
- Timeouts are enforced in `RequestManager`.
|
|
93
|
+
- A response is only considered valid if it reaches the pending UUID entry.
|
|
94
|
+
- If the remote side returns an `ERROR`, the pending request is rejected with a `VIOError`.
|
|
95
|
+
|
|
96
|
+
## Event Lifecycle
|
|
97
|
+
|
|
98
|
+
```mermaid
|
|
99
|
+
flowchart TD
|
|
100
|
+
A["Application calls event()"] --> B[VIO.sendEvent]
|
|
101
|
+
B --> C[serialize]
|
|
102
|
+
C --> D[Frame.encode EVENT]
|
|
103
|
+
D --> E[Transport send event]
|
|
104
|
+
E --> F[Remote peer receives frame]
|
|
105
|
+
F --> G[VIO.handle]
|
|
106
|
+
G --> H[handleEvent]
|
|
107
|
+
H --> I[Emit typed event]
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Key behavior
|
|
111
|
+
|
|
112
|
+
- Event payloads are serialized according to their runtime shape.
|
|
113
|
+
- JSON payloads are decoded with UTF-8 and `JSON.parse`.
|
|
114
|
+
- LINE payloads use the line codec.
|
|
115
|
+
- Binary and custom payloads are passed as `Uint8Array`.
|
|
116
|
+
|
|
117
|
+
## Strict Layer
|
|
118
|
+
|
|
119
|
+
`VIOStrict` is the typed integration layer for applications that want schemas and named channels.
|
|
120
|
+
|
|
121
|
+
- `event` validates outbound event payloads and inbound event payloads.
|
|
122
|
+
- `request` validates outbound request payloads and inbound response payloads.
|
|
123
|
+
- `transport` bridges raw byte transport and re-emits low-level transport events.
|
|
124
|
+
|
|
125
|
+
The strict layer does not replace `VIO`; it composes it.
|
|
126
|
+
|
|
127
|
+
## Transport Model
|
|
128
|
+
|
|
129
|
+
```mermaid
|
|
130
|
+
flowchart TD
|
|
131
|
+
A[VIO.transport] --> B[send event]
|
|
132
|
+
B --> C[Consumer transport adapter]
|
|
133
|
+
C --> D[WebSocket or equivalent]
|
|
134
|
+
D --> E[incoming bytes]
|
|
135
|
+
E --> F[VIO.handle]
|
|
136
|
+
F --> G[Protocol dispatch]
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### Key behavior
|
|
140
|
+
|
|
141
|
+
- The runtime stays transport-agnostic.
|
|
142
|
+
- Consumers decide how frames are written to the socket or stream.
|
|
143
|
+
- The library only emits encoded bytes and processes incoming bytes.
|
|
144
|
+
|
|
145
|
+
## Data Modes
|
|
146
|
+
|
|
147
|
+
Vortez IO supports four frame modes:
|
|
148
|
+
|
|
149
|
+
- `BINARY` for raw `Uint8Array` / `ArrayBuffer` payloads.
|
|
150
|
+
- `JSON` for structured object payloads.
|
|
151
|
+
- `LINE` for key-value style line payloads.
|
|
152
|
+
- `CUSTOM` for application-defined binary semantics.
|
|
153
|
+
|
|
154
|
+
Mode selection is handled by `VIO.serialize` and by the decoding branches in `VIO.handleEvent`, `VIO.handleRequest`, `VIO.handleResponse`, and `VIO.handleError`.
|
|
155
|
+
|
|
156
|
+
## Error Handling
|
|
157
|
+
|
|
158
|
+
Errors are treated as protocol data and runtime signals.
|
|
159
|
+
|
|
160
|
+
- `VIOError` is used for protocol validation and runtime failures.
|
|
161
|
+
- Decoding failures become `INVALID_DATA` or related protocol errors.
|
|
162
|
+
- Unknown types or modes are surfaced as protocol errors.
|
|
163
|
+
- Transport emission failures are re-emitted through the transport error channel with context.
|
|
164
|
+
|
|
165
|
+
### Key behavior
|
|
166
|
+
|
|
167
|
+
- If a request-bound error can be matched to a UUID, it is routed back through `RequestManager`.
|
|
168
|
+
- If an error frame has no UUID, it is emitted as a general runtime error.
|
|
169
|
+
- Invalid frames are rejected early to keep state predictable.
|
|
170
|
+
|
|
171
|
+
## Public API Map
|
|
172
|
+
|
|
173
|
+
- `VIO`: transport-aware runtime for requests, events, raw frames, and frame handling.
|
|
174
|
+
- `Frame`: low-level protocol encoder and decoder.
|
|
175
|
+
- `RequestManager`: pending request bookkeeping and timeout management.
|
|
176
|
+
- `VIOStrict`: typed wrapper over `VIO` with schema-validated channels.
|
|
177
|
+
- `VIOError`: protocol and runtime error type.
|
|
178
|
+
|
|
179
|
+
## Build And Distribution
|
|
180
|
+
|
|
181
|
+
```mermaid
|
|
182
|
+
flowchart LR
|
|
183
|
+
A[Source TypeScript] --> B[scripts/build.sh]
|
|
184
|
+
B --> C[build/]
|
|
185
|
+
C --> D[ES module package output]
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
The published package targets an ES module environment and ships compiled output from the `build/` directory.
|
|
189
|
+
|
|
190
|
+
## Recommended Documentation Map
|
|
191
|
+
|
|
192
|
+
To keep the documentation aligned with the codebase, split the docs by intent:
|
|
193
|
+
|
|
194
|
+
- README: short overview, install, and quick start.
|
|
195
|
+
- PROTOCOL.md: binary frame specification and wire-level rules.
|
|
196
|
+
- ARCHITECTURE.md: runtime layers and message flow.
|
|
197
|
+
- API reference: exported classes, methods, and types.
|
|
198
|
+
- Examples: minimal WebSocket integration and strict typed usage.
|
|
199
|
+
|
|
200
|
+
This architecture guide is the canonical high-level reference for how Vortez IO is structured.
|
package/package.json
CHANGED