@harapter/transport-jsonrpc-stdio 0.1.1
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/LICENSE +201 -0
- package/README.md +163 -0
- package/dist/index.d.ts +166 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +829 -0
- package/dist/index.js.map +1 -0
- package/package.json +46 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright 2026 Harapter contributors
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
package/README.md
ADDED
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# `@harapter/transport-jsonrpc-stdio`
|
|
2
|
+
|
|
3
|
+
`@harapter/transport-jsonrpc-stdio` is a bounded, bidirectional JSONL transport
|
|
4
|
+
for Provider Adapters whose official machine interface exchanges JSON-RPC-shaped
|
|
5
|
+
messages over Node readable and writable streams.
|
|
6
|
+
|
|
7
|
+
The package owns framing, request correlation, ordered inbound delivery,
|
|
8
|
+
backpressure, local wait controls, and connection disposal. It does not import
|
|
9
|
+
Provider SDKs or assign portable Harapter meaning to Provider methods and
|
|
10
|
+
payloads.
|
|
11
|
+
|
|
12
|
+
## Installation
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
pnpm add @harapter/transport-jsonrpc-stdio@next
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Public entrypoints
|
|
19
|
+
|
|
20
|
+
- `JsonRpcStdioTransport` sends requests, notifications, and responses and
|
|
21
|
+
exposes remote requests and notifications as one ordered async iterable.
|
|
22
|
+
- `JsonRpcInboundRequest` and `JsonRpcInboundNotification` preserve the remote
|
|
23
|
+
method and optional parameters for Adapter-level validation and mapping.
|
|
24
|
+
- `JsonRpcTransportError` provides stable transport failure codes with bounded
|
|
25
|
+
messages that do not include frames, stream errors, or identifiers.
|
|
26
|
+
- `JsonRpcRemoteError` remains safe under ordinary JSON and Node inspection;
|
|
27
|
+
`getRemoteError()` explicitly extracts the bounded remote code, message, and
|
|
28
|
+
data for Provider-owned validation and redaction.
|
|
29
|
+
- `JsonRpcDiagnostic` reports an unmatched or late response without exposing its
|
|
30
|
+
identifier or body.
|
|
31
|
+
- `abandonInboundRequest()` releases a remote request that the Provider has
|
|
32
|
+
authoritatively resolved without a client response; it emits no wire message.
|
|
33
|
+
- `requestAfterInbound()` resolves a response only after the sole inbound
|
|
34
|
+
consumer finishes handling every request or notification received earlier on
|
|
35
|
+
the wire.
|
|
36
|
+
- `isOpen()` distinguishes request-local failures from terminal transport state.
|
|
37
|
+
|
|
38
|
+
## Framing and limits
|
|
39
|
+
|
|
40
|
+
Each message is one UTF-8 JSON object followed by `\n`; inbound `\r\n` is also
|
|
41
|
+
accepted. By default the transport accepts either an omitted `jsonrpc` member or
|
|
42
|
+
the exact value `"2.0"`. `requireJsonRpcVersion` can require that exact member,
|
|
43
|
+
while `emitJsonRpcVersion` adds it to every outbound envelope.
|
|
44
|
+
`requireIntegerNumericIds` rejects fractional numeric request and response IDs
|
|
45
|
+
while retaining string and `null` IDs. This accommodates strict schemas such as
|
|
46
|
+
ACP v1 and official interfaces such as
|
|
47
|
+
[Codex App Server](https://developers.openai.com/codex/app-server), whose stdio
|
|
48
|
+
mode uses newline-delimited JSON and omits the standard JSON-RPC version member
|
|
49
|
+
on the wire.
|
|
50
|
+
|
|
51
|
+
Defaults are deliberately finite:
|
|
52
|
+
|
|
53
|
+
- `maxMessageBytes`: 1 MiB per encoded message, excluding the newline;
|
|
54
|
+
- `maxBufferedMessages`: 128 unread remote requests and notifications;
|
|
55
|
+
- `maxPendingRequests`: 128 outbound requests awaiting a response;
|
|
56
|
+
- `maxPendingInboundRequests`: 128 remote requests awaiting a response;
|
|
57
|
+
- `maxPendingWrites`: 128 active or queued writes;
|
|
58
|
+
- `requestTimeoutMs`: 30 seconds.
|
|
59
|
+
|
|
60
|
+
Limits must be positive safe integers. Timeouts must also be no greater than
|
|
61
|
+
2,147,483,647 milliseconds, the maximum delay Node timers preserve without
|
|
62
|
+
overflow. A limit violation fails the affected operation or, when it proves the
|
|
63
|
+
peer has exceeded an inbound bound, fails the connection.
|
|
64
|
+
|
|
65
|
+
## Lifecycle
|
|
66
|
+
|
|
67
|
+
The caller supplies and owns the streams. The transport never spawns, kills, or
|
|
68
|
+
restarts a process and never ends or destroys caller-owned streams. A caller may
|
|
69
|
+
provide `cleanup` to close its surrounding process or connection policy; the
|
|
70
|
+
transport invokes that callback at most once after explicit closure, malformed
|
|
71
|
+
input, stream failure, premature EOF, or another terminal transport failure. It
|
|
72
|
+
temporarily guards both streams against errors racing with that terminal path or
|
|
73
|
+
its awaited cleanup, then removes those guards before `close()` settles.
|
|
74
|
+
|
|
75
|
+
`close()` is idempotent. It rejects outstanding requests and writes with
|
|
76
|
+
`transport_closed`, completes a waiting inbound iterator normally, and awaits
|
|
77
|
+
the optional cleanup. A protocol or stream failure rejects inbound iteration
|
|
78
|
+
with its safe transport error. Stopping the sole inbound iterator also closes
|
|
79
|
+
the logical transport, because remote requests would otherwise have no consumer.
|
|
80
|
+
|
|
81
|
+
Requests and all write-producing operations share a serialized, bounded queue.
|
|
82
|
+
The transport waits for each Node write callback before starting the next frame.
|
|
83
|
+
A request that times out or is locally aborted before its queued write starts is
|
|
84
|
+
not sent. Once a write has started, however, the peer may already have received
|
|
85
|
+
the request.
|
|
86
|
+
|
|
87
|
+
Each remote request remains capacity-accounted until a response finishes,
|
|
88
|
+
connection termination clears it, or the consuming Adapter calls
|
|
89
|
+
`abandonInboundRequest()` after an authoritative Provider-side resolution. A
|
|
90
|
+
request with an in-progress response records deferred abandonment and remains
|
|
91
|
+
capacity-accounted until that response attempt settles. Both successful and
|
|
92
|
+
failed response attempts then release its local ownership.
|
|
93
|
+
|
|
94
|
+
`requestAfterInbound()` adds an explicit ordering barrier for protocols whose
|
|
95
|
+
response is a lifecycle boundary. The response parser snapshots the count of
|
|
96
|
+
earlier inbound messages, and the request resolves after the async consumer
|
|
97
|
+
advances past that snapshot. Messages received after the response are not part
|
|
98
|
+
of the barrier. The request remains capacity-accounted, and its timeout and
|
|
99
|
+
`AbortSignal` remain active, until the barrier settles. Connection termination
|
|
100
|
+
rejects a pending barrier; it cannot turn missing event handling into a
|
|
101
|
+
successful result.
|
|
102
|
+
|
|
103
|
+
`AbortSignal` and request timeout control only the caller's local response wait.
|
|
104
|
+
They do not send a Provider cancellation method and are never evidence of native
|
|
105
|
+
Run cancellation. A later response becomes a bounded `unmatched_response`
|
|
106
|
+
diagnostic rather than a successful result.
|
|
107
|
+
|
|
108
|
+
## Errors and sensitive data
|
|
109
|
+
|
|
110
|
+
Malformed JSON, invalid UTF-8, structurally ambiguous envelopes, oversized
|
|
111
|
+
messages, duplicate outstanding remote request identifiers, and inbound capacity
|
|
112
|
+
violations fail closed. Transport errors contain fixed messages and never attach
|
|
113
|
+
an original stream error or frame body.
|
|
114
|
+
|
|
115
|
+
Remote JSON-RPC errors are different: `JsonRpcRemoteError.getRemoteError()` is
|
|
116
|
+
an explicit raw-data extraction boundary for the consuming Adapter. Its return
|
|
117
|
+
value may contain sensitive data and must be validated and redacted before
|
|
118
|
+
becoming a Harapter error, event, diagnostic, or log entry. Logging the Error
|
|
119
|
+
object itself through ordinary JSON serialization or Node inspection remains
|
|
120
|
+
content-free. Inbound `method` and `params` have the same Provider-owned
|
|
121
|
+
validation and redaction requirement.
|
|
122
|
+
|
|
123
|
+
## Example
|
|
124
|
+
|
|
125
|
+
```ts
|
|
126
|
+
import { JsonRpcStdioTransport } from '@harapter/transport-jsonrpc-stdio';
|
|
127
|
+
|
|
128
|
+
const transport = new JsonRpcStdioTransport({
|
|
129
|
+
readable: controlledProcess.stdout,
|
|
130
|
+
writable: controlledProcess.stdin,
|
|
131
|
+
cleanup: () => stopControlledProcess(controlledProcess),
|
|
132
|
+
});
|
|
133
|
+
|
|
134
|
+
const inbound = (async () => {
|
|
135
|
+
for await (const message of transport.incoming()) {
|
|
136
|
+
// The Provider Adapter validates and maps each method and payload.
|
|
137
|
+
await handleProviderMessage(message);
|
|
138
|
+
}
|
|
139
|
+
})();
|
|
140
|
+
|
|
141
|
+
await transport.request('initialize', {
|
|
142
|
+
clientInfo: { name: 'harapter-provider', version: '0.0.0' },
|
|
143
|
+
});
|
|
144
|
+
await transport.close();
|
|
145
|
+
await inbound;
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
The process policy, initialization sequence, generated schemas, method
|
|
149
|
+
semantics, retries, Provider compatibility range, and portable event/error
|
|
150
|
+
mapping belong to the consuming Provider Adapter.
|
|
151
|
+
|
|
152
|
+
## Limitations
|
|
153
|
+
|
|
154
|
+
- This is not a process manager, Provider Adapter, generic agent loop, logger,
|
|
155
|
+
retry layer, or full JSON-RPC framework.
|
|
156
|
+
- Exactly one consumer may claim `incoming()`.
|
|
157
|
+
- Messages must fit on one JSONL frame; batch arrays and multiline framing are
|
|
158
|
+
rejected.
|
|
159
|
+
- Generic request result types provide TypeScript ergonomics only. Each Adapter
|
|
160
|
+
must validate untyped boundary data against its supported upstream schema.
|
|
161
|
+
- No Provider support claim follows from this package alone. A Provider still
|
|
162
|
+
needs an implementation, redacted fixtures, shared conformance evidence, and a
|
|
163
|
+
declared compatibility range.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
import type { Readable, Writable } from 'node:stream';
|
|
2
|
+
import { inspect } from 'node:util';
|
|
3
|
+
/** JSON-RPC identifier supported by the transport. */
|
|
4
|
+
export type JsonRpcId = string | number | null;
|
|
5
|
+
/** JSON-RPC error object returned by a remote peer. */
|
|
6
|
+
export interface JsonRpcErrorObject {
|
|
7
|
+
readonly code: number;
|
|
8
|
+
readonly message: string;
|
|
9
|
+
readonly data?: unknown;
|
|
10
|
+
}
|
|
11
|
+
/** Request initiated by the remote peer. */
|
|
12
|
+
export interface JsonRpcInboundRequest {
|
|
13
|
+
readonly kind: 'request';
|
|
14
|
+
readonly id: JsonRpcId;
|
|
15
|
+
readonly method: string;
|
|
16
|
+
readonly params?: unknown;
|
|
17
|
+
}
|
|
18
|
+
/** Notification emitted by the remote peer. */
|
|
19
|
+
export interface JsonRpcInboundNotification {
|
|
20
|
+
readonly kind: 'notification';
|
|
21
|
+
readonly method: string;
|
|
22
|
+
readonly params?: unknown;
|
|
23
|
+
}
|
|
24
|
+
/** Inbound messages that require Provider-level interpretation. */
|
|
25
|
+
export type JsonRpcInboundMessage = JsonRpcInboundRequest | JsonRpcInboundNotification;
|
|
26
|
+
/** Safe transport diagnostic without message content or remote identifiers. */
|
|
27
|
+
export interface JsonRpcDiagnostic {
|
|
28
|
+
readonly code: 'unmatched_response';
|
|
29
|
+
}
|
|
30
|
+
/** Stable transport failure categories for Provider error mapping. */
|
|
31
|
+
export type JsonRpcTransportErrorCode = 'capacity_exceeded' | 'cleanup_failed' | 'consumer_conflict' | 'invalid_configuration' | 'invalid_outbound_message' | 'malformed_message' | 'message_too_large' | 'request_aborted' | 'request_timeout' | 'response_not_pending' | 'stream_ended' | 'stream_failed' | 'transport_closed' | 'truncated_message' | 'write_failed';
|
|
32
|
+
/** Safe transport failure that never includes a frame or stream error body. */
|
|
33
|
+
export declare class JsonRpcTransportError extends Error {
|
|
34
|
+
readonly code: JsonRpcTransportErrorCode;
|
|
35
|
+
constructor(code: JsonRpcTransportErrorCode, message: string);
|
|
36
|
+
}
|
|
37
|
+
/** Safe remote failure with raw fields behind an explicit extraction method. */
|
|
38
|
+
export declare class JsonRpcRemoteError extends Error {
|
|
39
|
+
#private;
|
|
40
|
+
constructor(error: JsonRpcErrorObject);
|
|
41
|
+
/** Explicitly extract untrusted fields for Provider validation and redaction. */
|
|
42
|
+
getRemoteError(): JsonRpcErrorObject;
|
|
43
|
+
/** Keep generic JSON error logging bounded and content-free. */
|
|
44
|
+
toJSON(): Readonly<{
|
|
45
|
+
message: string;
|
|
46
|
+
name: string;
|
|
47
|
+
}>;
|
|
48
|
+
/** Keep Node inspection bounded and content-free. */
|
|
49
|
+
[inspect.custom](): string;
|
|
50
|
+
}
|
|
51
|
+
/** Request-local timeout and wait-abort controls. */
|
|
52
|
+
export interface JsonRpcRequestOptions {
|
|
53
|
+
readonly timeoutMs?: number;
|
|
54
|
+
readonly signal?: AbortSignal;
|
|
55
|
+
}
|
|
56
|
+
/** Explicit stream, lifecycle, and resource limits for one connection. */
|
|
57
|
+
export interface JsonRpcStdioTransportOptions {
|
|
58
|
+
readonly readable: Readable;
|
|
59
|
+
readonly writable: Writable;
|
|
60
|
+
readonly cleanup?: () => Promise<void> | void;
|
|
61
|
+
readonly emitJsonRpcVersion?: boolean;
|
|
62
|
+
readonly requireJsonRpcVersion?: boolean;
|
|
63
|
+
readonly requireIntegerNumericIds?: boolean;
|
|
64
|
+
readonly maxMessageBytes?: number;
|
|
65
|
+
readonly maxBufferedMessages?: number;
|
|
66
|
+
readonly maxPendingRequests?: number;
|
|
67
|
+
readonly maxPendingInboundRequests?: number;
|
|
68
|
+
readonly maxPendingWrites?: number;
|
|
69
|
+
readonly requestTimeoutMs?: number;
|
|
70
|
+
readonly onDiagnostic?: (diagnostic: JsonRpcDiagnostic) => void;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Bounded bidirectional JSONL RPC transport over caller-owned Node streams.
|
|
74
|
+
* It correlates responses but leaves Provider methods and lifecycle semantics
|
|
75
|
+
* to the consuming Adapter.
|
|
76
|
+
*/
|
|
77
|
+
export declare class JsonRpcStdioTransport {
|
|
78
|
+
private readonly readable;
|
|
79
|
+
private readonly writable;
|
|
80
|
+
private readonly cleanup;
|
|
81
|
+
private readonly emitJsonRpcVersion;
|
|
82
|
+
private readonly requireJsonRpcVersion;
|
|
83
|
+
private readonly requireIntegerNumericIds;
|
|
84
|
+
private readonly maxMessageBytes;
|
|
85
|
+
private readonly maxPendingRequests;
|
|
86
|
+
private readonly maxPendingInboundRequests;
|
|
87
|
+
private readonly maxPendingWrites;
|
|
88
|
+
private readonly requestTimeoutMs;
|
|
89
|
+
private readonly onDiagnostic;
|
|
90
|
+
private readonly inboundQueue;
|
|
91
|
+
private readonly pendingRequests;
|
|
92
|
+
private readonly pendingInboundRequestIds;
|
|
93
|
+
private readonly respondingInboundRequestIds;
|
|
94
|
+
private readonly abandoningInboundRequestIds;
|
|
95
|
+
private readonly terminalGuardStreams;
|
|
96
|
+
private readonly activeWriteRejectors;
|
|
97
|
+
private lineChunks;
|
|
98
|
+
private lineBytes;
|
|
99
|
+
private nextRequestId;
|
|
100
|
+
private pendingWrites;
|
|
101
|
+
private incomingClaimed;
|
|
102
|
+
private inboundAcknowledgedSequence;
|
|
103
|
+
private inboundSequence;
|
|
104
|
+
private readonly inboundBarrierWaiters;
|
|
105
|
+
private open;
|
|
106
|
+
private terminalError;
|
|
107
|
+
private cleanupFailure;
|
|
108
|
+
private cleanupPromise;
|
|
109
|
+
private writeTail;
|
|
110
|
+
private writableCallbackFailed;
|
|
111
|
+
private readonly handleReadableData;
|
|
112
|
+
private readonly handleReadableEnd;
|
|
113
|
+
private readonly handleStreamError;
|
|
114
|
+
private readonly handleWritableError;
|
|
115
|
+
private readonly handleStreamClose;
|
|
116
|
+
constructor(options: JsonRpcStdioTransportOptions);
|
|
117
|
+
/** Send a request and resolve it exactly once from its correlated response. */
|
|
118
|
+
request<TResult = unknown>(method: string, params?: unknown, options?: JsonRpcRequestOptions): Promise<TResult>;
|
|
119
|
+
/** Resolve a request only after earlier inbound messages were consumed. */
|
|
120
|
+
requestAfterInbound<TResult = unknown>(method: string, params?: unknown, options?: JsonRpcRequestOptions): Promise<TResult>;
|
|
121
|
+
private requestInternal;
|
|
122
|
+
/** Send a notification and wait until its complete frame is flushed. */
|
|
123
|
+
notify(method: string, params?: unknown): Promise<void>;
|
|
124
|
+
/** Iterate remote requests and notifications in wire order. */
|
|
125
|
+
incoming(): AsyncIterableIterator<JsonRpcInboundMessage>;
|
|
126
|
+
/** Respond successfully to one outstanding remote request. */
|
|
127
|
+
respond(id: JsonRpcId, result: unknown): Promise<void>;
|
|
128
|
+
/** Respond with a JSON-RPC error to one outstanding remote request. */
|
|
129
|
+
respondError(id: JsonRpcId, error: JsonRpcErrorObject): Promise<void>;
|
|
130
|
+
/**
|
|
131
|
+
* Release a remote request that the Provider authoritatively resolved without
|
|
132
|
+
* a client response. No wire message is emitted.
|
|
133
|
+
*/
|
|
134
|
+
abandonInboundRequest(id: JsonRpcId): boolean;
|
|
135
|
+
/** Whether the logical transport can still accept operations. */
|
|
136
|
+
isOpen(): boolean;
|
|
137
|
+
/** Close the logical transport and run caller-provided cleanup once. */
|
|
138
|
+
close(): Promise<void>;
|
|
139
|
+
private iterateIncoming;
|
|
140
|
+
private respondWithEnvelope;
|
|
141
|
+
private outboundEnvelope;
|
|
142
|
+
private encode;
|
|
143
|
+
private enqueueWrite;
|
|
144
|
+
private writeFrame;
|
|
145
|
+
private consumeChunk;
|
|
146
|
+
private appendLineSegment;
|
|
147
|
+
private consumeLine;
|
|
148
|
+
private consumeEnvelope;
|
|
149
|
+
private consumeMethodEnvelope;
|
|
150
|
+
private consumeResponseEnvelope;
|
|
151
|
+
private enqueueInbound;
|
|
152
|
+
private acknowledgeInbound;
|
|
153
|
+
private waitForInbound;
|
|
154
|
+
private settlePending;
|
|
155
|
+
private startPendingWrite;
|
|
156
|
+
private allocateRequestId;
|
|
157
|
+
private emitDiagnostic;
|
|
158
|
+
private assertOpen;
|
|
159
|
+
private fail;
|
|
160
|
+
private terminate;
|
|
161
|
+
private detachStreams;
|
|
162
|
+
private startCleanup;
|
|
163
|
+
private armTerminalErrorGuards;
|
|
164
|
+
private releaseTerminalErrorGuards;
|
|
165
|
+
}
|
|
166
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|