@standardserver/peer 0.0.12 → 0.0.18
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 +151 -0
- package/dist/index.d.mts +1 -2
- package/dist/index.d.ts +1 -2
- package/dist/index.mjs +14 -15
- package/package.json +5 -4
package/README.md
ADDED
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# @standardserver/peer
|
|
2
|
+
|
|
3
|
+
<div align="center">
|
|
4
|
+
<a href="https://codecov.io/gh/middleapi/standardserver">
|
|
5
|
+
<img alt="codecov" src="https://codecov.io/gh/middleapi/standardserver/branch/main/graph/badge.svg">
|
|
6
|
+
</a>
|
|
7
|
+
<a href="https://www.npmjs.com/package/@standardserver/peer">
|
|
8
|
+
<img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40standardserver%2Fpeer?logo=npm" />
|
|
9
|
+
</a>
|
|
10
|
+
<a href="https://github.com/middleapi/standardserver/blob/main/LICENSE">
|
|
11
|
+
<img alt="MIT License" src="https://img.shields.io/github/license/middleapi/standardserver?logo=open-source-initiative" />
|
|
12
|
+
</a>
|
|
13
|
+
<a href="https://discord.gg/TXEbwRBvQn">
|
|
14
|
+
<img alt="Discord" src="https://img.shields.io/discord/1308966753044398161?color=7389D8&label&logo=discord&logoColor=ffffff" />
|
|
15
|
+
</a>
|
|
16
|
+
<a href="https://deepwiki.com/middleapi/standardserver">
|
|
17
|
+
<img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
|
|
18
|
+
</a>
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
`@standardserver/peer` adapts message-based transports to the transport-agnostic request and response model defined by Standard Server.
|
|
22
|
+
|
|
23
|
+
Standard Server provides a unified interface for client-server communication across HTTP and message-based transports. It lets you write handlers and clients against the same request, response, body, and streaming primitives whether the underlying transport is Fetch, Node.js HTTP, WebSocket, MessagePort, or another peer-style channel.
|
|
24
|
+
|
|
25
|
+
This package is the peer adapter for that model. It converts between Standard Server requests and responses and a structured peer message protocol that can be sent through any transport capable of carrying strings or binary data.
|
|
26
|
+
|
|
27
|
+
## Entry Point
|
|
28
|
+
|
|
29
|
+
The package exports a single entry point:
|
|
30
|
+
|
|
31
|
+
| Export | Purpose |
|
|
32
|
+
| ---------------------- | ----------------------------------------------------------------------------- |
|
|
33
|
+
| `@standardserver/peer` | Peer adapter helpers for requests, responses, codecs, streams, and validators |
|
|
34
|
+
|
|
35
|
+
## Package overview
|
|
36
|
+
|
|
37
|
+
The main entry point exposes four groups of helpers:
|
|
38
|
+
|
|
39
|
+
| Group | Exports | Purpose |
|
|
40
|
+
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
|
|
41
|
+
| Peer runtime | `ClientPeer`, `ServerPeer` | Send Standard Server requests and responses over a peer transport |
|
|
42
|
+
| Message codec | `encodePeerMessage()`, `decodePeerMessage()` | Encode peer messages as strings or bytes for transport |
|
|
43
|
+
| Stream utilities | `toEventIterator()`, `EventStreamTransmitter`, `HibernationEventIterator` | Bridge peer messages with Standard Server event-stream semantics |
|
|
44
|
+
| Types and validators | `PeerMessage`, `PeerRequestMessage`, `PeerResponseMessage`, `PeerCancelMessage`, `PeerEventStreamMessage`, `PeerOctetStreamMessage`, `PeerStreamCancelMessage`, `ClientPeerSendMessage`, `ServerPeerSendMessage`, `isPeerMessage()`, `isPeerRequestMessage()`, `isPeerResponseMessage()`, `isPeerCancelMessage()`, `isPeerEventStreamMessage()`, `isPeerOctetStreamMessage()`, `isPeerStreamCancelMessage()`, `isClientPeerSendMessage()`, `isServerPeerSendMessage()` | Describe and validate the peer protocol payloads |
|
|
45
|
+
|
|
46
|
+
Use these helpers when you want Standard Server handlers or clients to run over message-based transports such as `MessagePort`, WebSocket, Electron IPC, or a custom channel.
|
|
47
|
+
|
|
48
|
+
## Request and response flow
|
|
49
|
+
|
|
50
|
+
`ClientPeer` starts a request and waits for a `StandardLazyResponse`. `ServerPeer` receives peer messages, reconstructs a `StandardLazyRequest`, calls your handler, and sends the resulting `StandardResponse` back over the same transport.
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
import type { StandardLazyRequest, StandardResponse } from '@standardserver/core'
|
|
54
|
+
import {
|
|
55
|
+
ClientPeer,
|
|
56
|
+
decodePeerMessage,
|
|
57
|
+
encodePeerMessage,
|
|
58
|
+
isClientPeerSendMessage,
|
|
59
|
+
isServerPeerSendMessage,
|
|
60
|
+
ServerPeer,
|
|
61
|
+
} from '@standardserver/peer'
|
|
62
|
+
|
|
63
|
+
async function handle(request: StandardLazyRequest): Promise<StandardResponse> {
|
|
64
|
+
const body = await request.resolveBody()
|
|
65
|
+
|
|
66
|
+
return {
|
|
67
|
+
status: 200,
|
|
68
|
+
headers: { 'content-type': 'application/json' },
|
|
69
|
+
body: {
|
|
70
|
+
ok: true,
|
|
71
|
+
method: request.method,
|
|
72
|
+
url: request.url,
|
|
73
|
+
received: body,
|
|
74
|
+
},
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
const { port1, port2 } = new MessageChannel()
|
|
79
|
+
|
|
80
|
+
const clientPeer = new ClientPeer(async (message) => {
|
|
81
|
+
port1.postMessage(await encodePeerMessage(message, { /** options */ }))
|
|
82
|
+
})
|
|
83
|
+
|
|
84
|
+
const serverPeer = new ServerPeer(async (message) => {
|
|
85
|
+
port2.postMessage(await encodePeerMessage(message, { /** options */ }))
|
|
86
|
+
})
|
|
87
|
+
|
|
88
|
+
port1.addEventListener('message', async (event) => {
|
|
89
|
+
const decoded = decodePeerMessage(event.data, { /** options */ })
|
|
90
|
+
|
|
91
|
+
if (decoded.matched && isServerPeerSendMessage(decoded.message)) {
|
|
92
|
+
await clientPeer.message(decoded.message)
|
|
93
|
+
}
|
|
94
|
+
})
|
|
95
|
+
|
|
96
|
+
port2.addEventListener('message', async (event) => {
|
|
97
|
+
const decoded = decodePeerMessage(event.data, { /** options */ })
|
|
98
|
+
|
|
99
|
+
if (decoded.matched && isClientPeerSendMessage(decoded.message)) {
|
|
100
|
+
await serverPeer.message(decoded.message, handle)
|
|
101
|
+
}
|
|
102
|
+
})
|
|
103
|
+
|
|
104
|
+
port1.start()
|
|
105
|
+
port2.start()
|
|
106
|
+
|
|
107
|
+
const response = await clientPeer.request({
|
|
108
|
+
method: 'POST',
|
|
109
|
+
url: '/echo',
|
|
110
|
+
headers: { 'content-type': 'application/json' },
|
|
111
|
+
body: { message: 'hello' },
|
|
112
|
+
})
|
|
113
|
+
|
|
114
|
+
const payload = await response.resolveBody()
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
> [!TIP]
|
|
118
|
+
> When encoding or decoding peer messages, you can pass additional options, such as `prefix`, to prevent collisions when the same peer is used for multiple purposes.
|
|
119
|
+
|
|
120
|
+
## Codec helpers
|
|
121
|
+
|
|
122
|
+
Use `encodePeerMessage()` and `decodePeerMessage()` to bridge between the peer protocol and your underlying transport.
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
import { decodePeerMessage, encodePeerMessage } from '@standardserver/peer'
|
|
126
|
+
|
|
127
|
+
const encoded = await encodePeerMessage(
|
|
128
|
+
{
|
|
129
|
+
id: '1',
|
|
130
|
+
kind: 'request',
|
|
131
|
+
json: { method: 'GET', url: '/health', headers: {}, body: undefined },
|
|
132
|
+
},
|
|
133
|
+
{ prefix: 'rpc:' },
|
|
134
|
+
)
|
|
135
|
+
|
|
136
|
+
const decoded = decodePeerMessage(encoded, { prefix: 'rpc:' })
|
|
137
|
+
|
|
138
|
+
if (decoded.matched) {
|
|
139
|
+
console.log(decoded.message.kind)
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Encoding rules:
|
|
144
|
+
|
|
145
|
+
1. Messages without binary payloads are encoded as strings.
|
|
146
|
+
2. Messages with binary payloads are encoded as `Uint8Array` values containing JSON, a delimiter byte, and the raw binary bytes.
|
|
147
|
+
3. The optional `prefix` lets you share the same transport between multiple protocols without collisions.
|
|
148
|
+
|
|
149
|
+
## Learn more
|
|
150
|
+
|
|
151
|
+
For the higher-level project overview, see the root [Standard Server README](../../README.md).
|
package/dist/index.d.mts
CHANGED
|
@@ -1,5 +1,4 @@
|
|
|
1
|
-
import { StandardRequest, StandardResponse, StandardLazyResponse, StandardLazyRequest } from '@standardserver/core';
|
|
2
|
-
import { EventStreamMessage } from '@standardserver/core/event-stream';
|
|
1
|
+
import { StandardRequest, EventStreamMessage, StandardResponse, StandardLazyResponse, StandardLazyRequest } from '@standardserver/core';
|
|
3
2
|
import { Queue, AsyncCleanupFn, AsyncIteratorClass } from '@standardserver/shared';
|
|
4
3
|
|
|
5
4
|
/**
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,4 @@
|
|
|
1
|
-
import { StandardRequest, StandardResponse, StandardLazyResponse, StandardLazyRequest } from '@standardserver/core';
|
|
2
|
-
import { EventStreamMessage } from '@standardserver/core/event-stream';
|
|
1
|
+
import { StandardRequest, EventStreamMessage, StandardResponse, StandardLazyResponse, StandardLazyRequest } from '@standardserver/core';
|
|
3
2
|
import { Queue, AsyncCleanupFn, AsyncIteratorClass } from '@standardserver/shared';
|
|
4
3
|
|
|
5
4
|
/**
|
package/dist/index.mjs
CHANGED
|
@@ -1,6 +1,5 @@
|
|
|
1
1
|
import { AsyncIteratorClass, isTypescriptObject, isAsyncIteratorObject, Queue, SequentialIdGenerator, omit, emitUnhandledRejection, AbortError, stringifyJSON } from '@standardserver/shared';
|
|
2
|
-
import { generateContentDisposition, flattenStandardHeader, getFilenameFromContentDisposition, isStandardRequest, isStandardResponse } from '@standardserver/core';
|
|
3
|
-
import { withEventIteratorEventMeta, EventIteratorErrorEvent, unwrapEventIteratorEvent } from '@standardserver/core/event-stream';
|
|
2
|
+
import { withEventIteratorEventMeta, EventIteratorErrorEvent, unwrapEventIteratorEvent, generateContentDisposition, flattenStandardHeader, getFilenameFromContentDisposition, isStandardRequest, isStandardResponse } from '@standardserver/core';
|
|
4
3
|
|
|
5
4
|
function toEventIterator(queue, cleanup) {
|
|
6
5
|
return new AsyncIteratorClass(async () => {
|
|
@@ -99,16 +98,16 @@ function toOctetStream(queue, cleanup) {
|
|
|
99
98
|
controller.enqueue(binary instanceof Uint8Array ? binary : new Uint8Array(await binary.arrayBuffer()));
|
|
100
99
|
}
|
|
101
100
|
if (json.close) {
|
|
102
|
-
await cleanup({
|
|
101
|
+
await cleanup({ kind: "success" });
|
|
103
102
|
controller.close();
|
|
104
103
|
}
|
|
105
104
|
} catch (error) {
|
|
106
|
-
await cleanup({
|
|
105
|
+
await cleanup({ kind: "error", error });
|
|
107
106
|
controller.error(error);
|
|
108
107
|
}
|
|
109
108
|
},
|
|
110
|
-
async cancel() {
|
|
111
|
-
await cleanup({
|
|
109
|
+
async cancel(error) {
|
|
110
|
+
await cleanup({ kind: "cancelled", error });
|
|
112
111
|
}
|
|
113
112
|
});
|
|
114
113
|
}
|
|
@@ -202,7 +201,7 @@ function toStandardBody(message, cleanup) {
|
|
|
202
201
|
errorRef = { value: error };
|
|
203
202
|
throw error;
|
|
204
203
|
} finally {
|
|
205
|
-
await cleanup(errorRef ? {
|
|
204
|
+
await cleanup(errorRef ? { kind: "error", error: errorRef.value } : { kind: "success" });
|
|
206
205
|
}
|
|
207
206
|
};
|
|
208
207
|
return { resolveBody };
|
|
@@ -348,11 +347,11 @@ class ClientPeer {
|
|
|
348
347
|
const resolve = state.resolve;
|
|
349
348
|
state.resolve = void 0;
|
|
350
349
|
try {
|
|
351
|
-
const decoded = toStandardBody(message, async (
|
|
352
|
-
if (
|
|
353
|
-
await this.abortById(id, error);
|
|
350
|
+
const decoded = toStandardBody(message, async (cleanupState) => {
|
|
351
|
+
if (cleanupState.kind === "cancelled") {
|
|
352
|
+
await this.abortById(id, cleanupState.error);
|
|
354
353
|
} else if (state.eventStreamMessageQueue || state.octetStreamMessageQueue) {
|
|
355
|
-
await this.closeById(id, error);
|
|
354
|
+
await this.closeById(id, cleanupState.error);
|
|
356
355
|
}
|
|
357
356
|
});
|
|
358
357
|
state.eventStreamMessageQueue = decoded.eventStreamMessageQueue;
|
|
@@ -554,8 +553,8 @@ class HibernationEventIterator extends AsyncIteratorClass {
|
|
|
554
553
|
constructor(hibernationCallback) {
|
|
555
554
|
super(async () => {
|
|
556
555
|
throw new Error("Cannot use hibernating iterator directly");
|
|
557
|
-
}, async ({
|
|
558
|
-
if (
|
|
556
|
+
}, async ({ kind }) => {
|
|
557
|
+
if (kind === "cancelled") {
|
|
559
558
|
throw new Error("Cannot use hibernating iterator directly");
|
|
560
559
|
}
|
|
561
560
|
});
|
|
@@ -599,8 +598,8 @@ class ServerPeer {
|
|
|
599
598
|
this.requests.set(id, state);
|
|
600
599
|
const signal = controller.signal;
|
|
601
600
|
try {
|
|
602
|
-
const decoded = toStandardBody(message, async ({
|
|
603
|
-
if (
|
|
601
|
+
const decoded = toStandardBody(message, async ({ kind }) => {
|
|
602
|
+
if (kind === "cancelled" && (state.eventStreamMessageQueue || state.octetStreamMessageQueue)) {
|
|
604
603
|
state.eventStreamMessageQueue = void 0;
|
|
605
604
|
state.octetStreamMessageQueue = void 0;
|
|
606
605
|
await this.send({ id, kind: "stream/cancel" });
|
package/package.json
CHANGED
|
@@ -1,16 +1,17 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@standardserver/peer",
|
|
3
3
|
"type": "module",
|
|
4
|
-
"version": "0.0.
|
|
4
|
+
"version": "0.0.18",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://standardserver.dev",
|
|
7
7
|
"repository": {
|
|
8
8
|
"type": "git",
|
|
9
|
-
"url": "git+https://github.com/
|
|
9
|
+
"url": "git+https://github.com/middleapi/standardserver.git",
|
|
10
10
|
"directory": "packages/peer"
|
|
11
11
|
},
|
|
12
12
|
"sideEffects": false,
|
|
13
13
|
"exports": {
|
|
14
|
+
"./package.json": "./package.json",
|
|
14
15
|
".": {
|
|
15
16
|
"types": "./dist/index.d.mts",
|
|
16
17
|
"import": "./dist/index.mjs",
|
|
@@ -21,8 +22,8 @@
|
|
|
21
22
|
"dist"
|
|
22
23
|
],
|
|
23
24
|
"dependencies": {
|
|
24
|
-
"@standardserver/core": "0.0.
|
|
25
|
-
"@standardserver/shared": "0.0.
|
|
25
|
+
"@standardserver/core": "0.0.18",
|
|
26
|
+
"@standardserver/shared": "0.0.18"
|
|
26
27
|
},
|
|
27
28
|
"scripts": {
|
|
28
29
|
"build": "unbuild",
|