agentrail-core 0.0.0 → 0.2.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/LICENSE +201 -0
- package/README.md +50 -0
- package/dist/collector.d.ts +75 -0
- package/dist/collector.js +182 -0
- package/dist/event.d.ts +154 -0
- package/dist/event.js +23 -0
- package/dist/hash.d.ts +17 -0
- package/dist/hash.js +40 -0
- package/dist/id.d.ts +10 -0
- package/dist/id.js +17 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.js +16 -0
- package/dist/marker.d.ts +40 -0
- package/dist/marker.js +102 -0
- package/dist/session.d.ts +40 -0
- package/dist/session.js +69 -0
- package/dist/structured-fields.d.ts +51 -0
- package/dist/structured-fields.js +246 -0
- package/dist/trace-handoff.d.ts +58 -0
- package/dist/trace-handoff.js +141 -0
- package/dist/trace.d.ts +7 -0
- package/dist/trace.js +33 -0
- package/dist/version.d.ts +7 -0
- package/dist/version.js +7 -0
- package/dist/web-bot-auth.d.ts +76 -0
- package/dist/web-bot-auth.js +534 -0
- package/package.json +28 -3
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 [yyyy] [name of copyright owner]
|
|
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,50 @@
|
|
|
1
|
+
# agentrail-core
|
|
2
|
+
|
|
3
|
+
What every Agentrail component shares, wherever the Fetch API and WebCrypto
|
|
4
|
+
run (Cloudflare Workers, Vercel's edge, Node, browsers): the event the
|
|
5
|
+
collector takes, as types; markers, minted and read (`parseMarker`) as the
|
|
6
|
+
collector's engine reads them; the keyed hash a workspace hashes addresses
|
|
7
|
+
and principals with, and its key's id; W3C trace context; the session
|
|
8
|
+
cookie, which ends after 30 minutes idle and a day at most, its id a UUIDv7
|
|
9
|
+
that carries its start; and the collector client. Its `send(event,
|
|
10
|
+
deadline)` resolves once the call carrying the event has ended: one call is
|
|
11
|
+
under way at a time, and what is sent meanwhile goes in the next, together.
|
|
12
|
+
It retries what the network or the collector failed after a random wait,
|
|
13
|
+
never sooner than a `Retry-After`, ends every call by its deadline, and
|
|
14
|
+
tells `onError` of every call given up. And the Web Bot Auth check
|
|
15
|
+
(`createSignatureVerifier`): a request's `Signature-Agent`,
|
|
16
|
+
`Signature-Input` and `Signature` checked against the keys the named agent
|
|
17
|
+
publishes at its `/.well-known/http-message-signatures-directory`, read once
|
|
18
|
+
per `max-age` and only from the known signers' hosts (`KNOWN_SIGNERS`) and
|
|
19
|
+
the ones a site names, since a caller chooses the URL; Ed25519, RSA-PSS-SHA512 and ECDSA-P256; the outcome is
|
|
20
|
+
`verified`, `invalid` (a forged or stale signature, or a key the directory
|
|
21
|
+
does not hold), `directory_unreachable` or `unsupported`, so a directory that
|
|
22
|
+
is down is never read as a forgery and a signature it does not read is never
|
|
23
|
+
called one.
|
|
24
|
+
|
|
25
|
+
`agentrail-edge` and `agentrail-browser` are built on it; a component of
|
|
26
|
+
your own can be too.
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
npm install agentrail-core
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Before 1.0, a minor version (0.1 to 0.2) may change what the package offers.
|
|
33
|
+
|
|
34
|
+
## Authenticated trace handoff
|
|
35
|
+
|
|
36
|
+
`signTraceHandoff(input, hashKey)` and `verifyTraceHandoff(token, expected)`
|
|
37
|
+
share a versioned, domain-separated HMAC-SHA256 format. Verification binds the
|
|
38
|
+
trace parent, key ID, method and exact origin-form target, and refuses future
|
|
39
|
+
or older-than-60-second tokens. `traceHandoffTarget(url)` retains encoded path
|
|
40
|
+
and query bytes, including a trailing empty query, and excludes the fragment.
|
|
41
|
+
The compatibility contract contains an independently calculated golden token.
|
|
42
|
+
|
|
43
|
+
`readTraceHandoff` returns an unverified candidate for synchronous OTel
|
|
44
|
+
propagators. Its signature must verify over the returned bytes before its
|
|
45
|
+
context becomes trusted. The async verifier performs that check with WebCrypto;
|
|
46
|
+
`agentrail-node` performs it synchronously before OTel chooses a parent.
|
|
47
|
+
|
|
48
|
+
## Licence
|
|
49
|
+
|
|
50
|
+
[Apache-2.0](LICENSE).
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import type { AgentrailEvent, Component } from './event.js';
|
|
2
|
+
/**
|
|
3
|
+
* Sends a component's events to the collector, `POST <endpoint>/ingest/events`
|
|
4
|
+
* with the source's secret: an edge sends each request's event after the
|
|
5
|
+
* answer, through its platform's `waitUntil`, off the request's path.
|
|
6
|
+
*
|
|
7
|
+
* One call at a time. An event sent while no call is under way goes at once;
|
|
8
|
+
* one sent while a call is under way waits, and goes with every other that
|
|
9
|
+
* waited in the next call, as Kafka's producer batches with no linger: a
|
|
10
|
+
* quiet site sends a call per event, a busy one about a call per round trip
|
|
11
|
+
* to the collector. A call goes from a send still waiting on it: a platform
|
|
12
|
+
* cancels what a request left running once its `waitUntil` has ended, so a
|
|
13
|
+
* call never rides on a request that is done.
|
|
14
|
+
*
|
|
15
|
+
* A call that fails because the network or the collector did (no answer, a
|
|
16
|
+
* 5xx, a 429, or no answer within the try's time) is tried again, after a
|
|
17
|
+
* random part of 250 ms and then of 1 s, so components that failed together
|
|
18
|
+
* do not try again together, and never sooner than a `Retry-After` the
|
|
19
|
+
* collector sent; each try sends the same events, which the collector counts
|
|
20
|
+
* as duplicates once stored. A call ends by its events' deadline: no try or
|
|
21
|
+
* wait starts that would end past it. A call the collector refuses (any other
|
|
22
|
+
* 4xx: a revoked secret, an event it cannot read) is not tried again. Either
|
|
23
|
+
* way the events are given up and the failure goes to `onError`, which logs
|
|
24
|
+
* it unless told otherwise, so a lost collector never fails the platform
|
|
25
|
+
* awaiting a send. Anything else is a fault here, and is thrown.
|
|
26
|
+
*/
|
|
27
|
+
export interface CollectorOptions {
|
|
28
|
+
/** The collector's origin, such as `https://api.agentrail.dev`. */
|
|
29
|
+
readonly endpoint: string;
|
|
30
|
+
/** The source's secret, as created for this component. */
|
|
31
|
+
readonly secret: string;
|
|
32
|
+
readonly component: Component;
|
|
33
|
+
/** Events per call; the collector takes calls of up to 16 MB. */
|
|
34
|
+
readonly batchSize?: number;
|
|
35
|
+
/** Tries per call, the first included. */
|
|
36
|
+
readonly attempts?: number;
|
|
37
|
+
/**
|
|
38
|
+
* How long one try may take, its answer read included, before it counts
|
|
39
|
+
* as failed and is tried again; 10 s by default, and never past the
|
|
40
|
+
* call's deadline.
|
|
41
|
+
*/
|
|
42
|
+
readonly timeoutMs?: number;
|
|
43
|
+
/** Told of each call whose events were given up. Logs by default. */
|
|
44
|
+
readonly onError?: (error: Error) => void;
|
|
45
|
+
readonly fetch?: typeof fetch;
|
|
46
|
+
readonly sleep?: (ms: number) => Promise<void>;
|
|
47
|
+
}
|
|
48
|
+
export interface Collector {
|
|
49
|
+
/**
|
|
50
|
+
* Sends an event, and resolves once the call carrying it has ended: taken,
|
|
51
|
+
* or given up and told to `onError`. `deadline`, in milliseconds since the
|
|
52
|
+
* epoch, is when that call must end, every try and wait included.
|
|
53
|
+
*/
|
|
54
|
+
send(event: AgentrailEvent, deadline: number): Promise<void>;
|
|
55
|
+
}
|
|
56
|
+
/** The collector refused a call: trying again would be refused again. */
|
|
57
|
+
export declare class CollectorRefusedError extends Error {
|
|
58
|
+
readonly status: number;
|
|
59
|
+
readonly name = "CollectorRefusedError";
|
|
60
|
+
constructor(status: number, message: string);
|
|
61
|
+
}
|
|
62
|
+
/** One try failed on the collector's side (a 5xx, a 429): worth another. */
|
|
63
|
+
export declare class CollectorFailedError extends Error {
|
|
64
|
+
readonly status: number;
|
|
65
|
+
readonly name = "CollectorFailedError";
|
|
66
|
+
constructor(status: number, message: string);
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* No call got through: the network, or the collector, failed every try, or
|
|
70
|
+
* the deadline left no time for another.
|
|
71
|
+
*/
|
|
72
|
+
export declare class CollectorUnavailableError extends Error {
|
|
73
|
+
readonly name = "CollectorUnavailableError";
|
|
74
|
+
}
|
|
75
|
+
export declare function createCollector(options: CollectorOptions): Collector;
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
/** The collector refused a call: trying again would be refused again. */
|
|
2
|
+
export class CollectorRefusedError extends Error {
|
|
3
|
+
status;
|
|
4
|
+
name = 'CollectorRefusedError';
|
|
5
|
+
constructor(status, message) {
|
|
6
|
+
super(message);
|
|
7
|
+
this.status = status;
|
|
8
|
+
}
|
|
9
|
+
}
|
|
10
|
+
/** One try failed on the collector's side (a 5xx, a 429): worth another. */
|
|
11
|
+
export class CollectorFailedError extends Error {
|
|
12
|
+
status;
|
|
13
|
+
name = 'CollectorFailedError';
|
|
14
|
+
constructor(status, message) {
|
|
15
|
+
super(message);
|
|
16
|
+
this.status = status;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* No call got through: the network, or the collector, failed every try, or
|
|
21
|
+
* the deadline left no time for another.
|
|
22
|
+
*/
|
|
23
|
+
export class CollectorUnavailableError extends Error {
|
|
24
|
+
name = 'CollectorUnavailableError';
|
|
25
|
+
}
|
|
26
|
+
/** The longest wait before each try after the first; each wait is a random part of it. */
|
|
27
|
+
const BACKOFF_MS = [250, 1_000];
|
|
28
|
+
function retriable(status) {
|
|
29
|
+
return status === 429 || status >= 500;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* How long a `Retry-After` asks to wait, in milliseconds: delay-seconds or an
|
|
33
|
+
* HTTP date (RFC 9110, 10.2.3). Null for none, or for one that is neither: it
|
|
34
|
+
* asks for nothing this client can read.
|
|
35
|
+
*/
|
|
36
|
+
function retryAfterMs(value, now) {
|
|
37
|
+
if (value === null)
|
|
38
|
+
return null;
|
|
39
|
+
const text = value.trim();
|
|
40
|
+
if (/^\d+$/u.test(text))
|
|
41
|
+
return Number(text) * 1_000;
|
|
42
|
+
const at = Date.parse(text);
|
|
43
|
+
return Number.isNaN(at) ? null : Math.max(0, at - now);
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* The try outran its deadline. Fetch rejects with the signal's reason, a
|
|
47
|
+
* `TimeoutError`; a runtime that does not pass the reason on rejects with an
|
|
48
|
+
* `AbortError`, and the deadline's is the only signal a try has.
|
|
49
|
+
*/
|
|
50
|
+
function timedOut(error) {
|
|
51
|
+
return (error instanceof DOMException &&
|
|
52
|
+
(error.name === 'TimeoutError' || error.name === 'AbortError'));
|
|
53
|
+
}
|
|
54
|
+
export function createCollector(options) {
|
|
55
|
+
const { endpoint, secret, component, batchSize = 500, attempts = 3, timeoutMs = 10_000, onError = (error) => {
|
|
56
|
+
console.error('agentrail: events were not sent', error);
|
|
57
|
+
}, fetch: send = fetch, sleep = (ms) => new Promise((resolve) => {
|
|
58
|
+
setTimeout(resolve, ms);
|
|
59
|
+
}), } = options;
|
|
60
|
+
const url = new URL('/ingest/events', endpoint);
|
|
61
|
+
const queue = [];
|
|
62
|
+
/** The calls under way; null when none is. */
|
|
63
|
+
let out = null;
|
|
64
|
+
async function deliver(events, deadline) {
|
|
65
|
+
const body = JSON.stringify({
|
|
66
|
+
component: { ...component, surfaces: [...component.surfaces] },
|
|
67
|
+
events,
|
|
68
|
+
});
|
|
69
|
+
let last = null;
|
|
70
|
+
let tries = 0;
|
|
71
|
+
// What the collector last asked a try to wait, at least.
|
|
72
|
+
let asked = null;
|
|
73
|
+
for (let attempt = 0; attempt < attempts; attempt += 1) {
|
|
74
|
+
const longest = BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length) - 1];
|
|
75
|
+
// One call after another: a retry waits out the failure before it.
|
|
76
|
+
const wait = longest === undefined
|
|
77
|
+
? 0
|
|
78
|
+
: Math.max(Math.random() * longest, asked ?? 0);
|
|
79
|
+
if (Date.now() + wait >= deadline)
|
|
80
|
+
break;
|
|
81
|
+
if (longest !== undefined)
|
|
82
|
+
await sleep(wait);
|
|
83
|
+
const left = deadline - Date.now();
|
|
84
|
+
if (left <= 0)
|
|
85
|
+
break;
|
|
86
|
+
tries += 1;
|
|
87
|
+
let response;
|
|
88
|
+
// What the collector said; a success says nothing more worth reading.
|
|
89
|
+
let answer;
|
|
90
|
+
try {
|
|
91
|
+
// One deadline for the whole try: a collector that sends its headers
|
|
92
|
+
// and never finishes its body holds the try no longer than one that
|
|
93
|
+
// never answers.
|
|
94
|
+
response = await send(url, {
|
|
95
|
+
method: 'POST',
|
|
96
|
+
headers: {
|
|
97
|
+
authorization: `Bearer ${secret}`,
|
|
98
|
+
'content-type': 'application/json',
|
|
99
|
+
},
|
|
100
|
+
body,
|
|
101
|
+
signal: AbortSignal.timeout(Math.min(timeoutMs, left)),
|
|
102
|
+
});
|
|
103
|
+
answer = response.ok ? null : await response.text();
|
|
104
|
+
}
|
|
105
|
+
catch (error) {
|
|
106
|
+
// Fetch rejects only when the network failed, before or while the
|
|
107
|
+
// answer arrived, or the deadline came first: nothing was read, so
|
|
108
|
+
// the call is tried again.
|
|
109
|
+
if (!(error instanceof TypeError) && !timedOut(error))
|
|
110
|
+
throw error;
|
|
111
|
+
last = error;
|
|
112
|
+
asked = null;
|
|
113
|
+
continue;
|
|
114
|
+
}
|
|
115
|
+
if (answer === null) {
|
|
116
|
+
try {
|
|
117
|
+
await response.body?.cancel();
|
|
118
|
+
}
|
|
119
|
+
catch (error) {
|
|
120
|
+
// The collector took the call: a body whose connection broke after
|
|
121
|
+
// its status changes nothing it said.
|
|
122
|
+
if (!(error instanceof TypeError))
|
|
123
|
+
throw error;
|
|
124
|
+
}
|
|
125
|
+
return;
|
|
126
|
+
}
|
|
127
|
+
if (!retriable(response.status))
|
|
128
|
+
throw new CollectorRefusedError(response.status, `The collector refused ${String(events.length)} events (${String(response.status)}): ${answer}`);
|
|
129
|
+
last = new CollectorFailedError(response.status, `The collector answered ${String(response.status)}: ${answer}`);
|
|
130
|
+
asked = retryAfterMs(response.headers.get('retry-after'), Date.now());
|
|
131
|
+
}
|
|
132
|
+
const outOfTime = tries < attempts;
|
|
133
|
+
throw new CollectorUnavailableError(`${String(events.length)} events were not sent after ${String(tries)} ${tries === 1 ? 'try' : 'tries'}${outOfTime ? ', with no time left before their deadline' : ''}.`, last === null ? undefined : { cause: last });
|
|
134
|
+
}
|
|
135
|
+
/** Sends what was taken off the queue, by the earliest deadline among it. */
|
|
136
|
+
async function sendTaken(taken) {
|
|
137
|
+
const deadline = Math.min(...taken.map((queued) => queued.deadline));
|
|
138
|
+
const events = taken.map((queued) => queued.event);
|
|
139
|
+
const batches = [];
|
|
140
|
+
for (let at = 0; at < events.length; at += batchSize)
|
|
141
|
+
batches.push(events.slice(at, at + batchSize));
|
|
142
|
+
await Promise.all(batches.map(async (batch) => {
|
|
143
|
+
try {
|
|
144
|
+
await deliver(batch, deadline);
|
|
145
|
+
}
|
|
146
|
+
catch (error) {
|
|
147
|
+
// Given up: told to onError, which logs unless told otherwise.
|
|
148
|
+
if (error instanceof CollectorRefusedError ||
|
|
149
|
+
error instanceof CollectorUnavailableError) {
|
|
150
|
+
onError(error);
|
|
151
|
+
return;
|
|
152
|
+
}
|
|
153
|
+
throw error;
|
|
154
|
+
}
|
|
155
|
+
}));
|
|
156
|
+
}
|
|
157
|
+
return {
|
|
158
|
+
async send(event, deadline) {
|
|
159
|
+
const queued = { event, deadline };
|
|
160
|
+
queue.push(queued);
|
|
161
|
+
// The call under way ends first, however it ends: the send that started
|
|
162
|
+
// it reports a fault.
|
|
163
|
+
while (out !== null)
|
|
164
|
+
await Promise.allSettled([out]);
|
|
165
|
+
// Carried by a call that has ended.
|
|
166
|
+
if (!queue.includes(queued))
|
|
167
|
+
return;
|
|
168
|
+
const calls = (async () => {
|
|
169
|
+
try {
|
|
170
|
+
await sendTaken(queue.splice(0, queue.length));
|
|
171
|
+
}
|
|
172
|
+
finally {
|
|
173
|
+
out = null;
|
|
174
|
+
}
|
|
175
|
+
})();
|
|
176
|
+
out = calls;
|
|
177
|
+
// This send waits on the call it started, so the request it belongs to
|
|
178
|
+
// keeps the call alive to its end.
|
|
179
|
+
await calls;
|
|
180
|
+
},
|
|
181
|
+
};
|
|
182
|
+
}
|
package/dist/event.d.ts
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One event as a component sends it to the collector (`POST /ingest/events`):
|
|
3
|
+
* the journey engine's event less `tenant` and `observedAt`, which the
|
|
4
|
+
* collector stamps from the source's workspace and its own clock, and
|
|
5
|
+
* `hashKeyId`, which it stamps from the key the call names.
|
|
6
|
+
*
|
|
7
|
+
* The engine, private to Argus, holds the schema the collector checks; this
|
|
8
|
+
* package holds the same shape as types, so no component imports the
|
|
9
|
+
* engine. The edge's and the browser's tests check every call they send
|
|
10
|
+
* against the contract Argus writes (`packages/contract`).
|
|
11
|
+
*/
|
|
12
|
+
export declare const SURFACES: readonly ["edge", "firewall", "browser", "http", "mcp", "a2a", "genai", "auth", "payment", "custom"];
|
|
13
|
+
export type Surface = (typeof SURFACES)[number];
|
|
14
|
+
/** Whose clock wrote `start` and `end`. */
|
|
15
|
+
export type ClockSource = 'edge' | 'backend' | 'browser' | 'third_party';
|
|
16
|
+
export type SpanKind = 'server' | 'client' | 'internal' | 'producer' | 'consumer';
|
|
17
|
+
/** What a verified principal is. Self-reported identity is never a principal. */
|
|
18
|
+
export type PrincipalKind = 'user' | 'agent_registration' | 'agent_instance' | 'oauth_client' | 'api_key';
|
|
19
|
+
/**
|
|
20
|
+
* What became of a request's Web Bot Auth signature at the component that
|
|
21
|
+
* saw it; only `verified` says who sent the request.
|
|
22
|
+
*/
|
|
23
|
+
export type SignatureOutcome = 'verified' | 'invalid' | 'directory_unreachable' | 'unsupported' | 'unchecked';
|
|
24
|
+
export type RegistrationPhase = 'created' | 'claim_completed' | 'expired' | 'revoked';
|
|
25
|
+
export interface SpanContext {
|
|
26
|
+
readonly traceId: string;
|
|
27
|
+
readonly spanId: string;
|
|
28
|
+
}
|
|
29
|
+
export interface AgentrailEvent {
|
|
30
|
+
/** Bumped when a field's meaning changes; stored events are read back. */
|
|
31
|
+
readonly schemaVersion: 1;
|
|
32
|
+
/** Minted here, so a duplicate delivery is the same event. */
|
|
33
|
+
readonly id: string;
|
|
34
|
+
readonly surface: Surface;
|
|
35
|
+
/** What happened, e.g. `http.request`, `tool.call`. */
|
|
36
|
+
readonly kind: string;
|
|
37
|
+
/** This component's clock, milliseconds since the epoch. */
|
|
38
|
+
readonly start: number;
|
|
39
|
+
/** Null for a point event. */
|
|
40
|
+
readonly end: number | null;
|
|
41
|
+
readonly clock: ClockSource;
|
|
42
|
+
/** `argus` for our own components; `other` for anything else. */
|
|
43
|
+
readonly emittedBy: 'argus' | 'other';
|
|
44
|
+
/** OpenTelemetry resource: `service.name` and `service.instance.id`. */
|
|
45
|
+
readonly resource: {
|
|
46
|
+
readonly serviceName: string;
|
|
47
|
+
readonly serviceInstanceId: string | null;
|
|
48
|
+
};
|
|
49
|
+
readonly span: {
|
|
50
|
+
readonly traceId: string;
|
|
51
|
+
readonly spanId: string;
|
|
52
|
+
readonly parentSpanId: string | null;
|
|
53
|
+
readonly kind: SpanKind;
|
|
54
|
+
/** Entered from outside: a parent it names came from whoever called. */
|
|
55
|
+
readonly publicEntry: boolean;
|
|
56
|
+
readonly subtreeSpanIds: string[];
|
|
57
|
+
readonly links: SpanContext[];
|
|
58
|
+
} | null;
|
|
59
|
+
/** `session.id` and `session.previous_id`, set by our edge. */
|
|
60
|
+
readonly session: {
|
|
61
|
+
readonly id: string;
|
|
62
|
+
readonly previousId: string | null;
|
|
63
|
+
} | null;
|
|
64
|
+
readonly http: {
|
|
65
|
+
readonly method: string;
|
|
66
|
+
readonly host: string;
|
|
67
|
+
/** The path with the allowlisted query. */
|
|
68
|
+
readonly path: string;
|
|
69
|
+
readonly status: number | null;
|
|
70
|
+
readonly location: string | null;
|
|
71
|
+
readonly contentType: string | null;
|
|
72
|
+
/** The addresses on the site's own hosts a response named, as requested. */
|
|
73
|
+
readonly linksOut: string[];
|
|
74
|
+
} | null;
|
|
75
|
+
/**
|
|
76
|
+
* Self-reported or network facts: features, never proofs, and what the
|
|
77
|
+
* collector's classifier of who the caller is reads. A component sends
|
|
78
|
+
* each of the later ones where it captured it; the collector fills null
|
|
79
|
+
* where a component sent nothing.
|
|
80
|
+
*/
|
|
81
|
+
readonly actor: {
|
|
82
|
+
/** Keyed hash of the client address. */
|
|
83
|
+
readonly egress: string | null;
|
|
84
|
+
readonly userAgent: string | null;
|
|
85
|
+
/** MCP `clientInfo` name, or another client self-description. */
|
|
86
|
+
readonly client: string | null;
|
|
87
|
+
/** The client software's own version: an MCP `clientInfo.version`. */
|
|
88
|
+
readonly clientVersion?: string | null | undefined;
|
|
89
|
+
/** The protocol version the client spoke. */
|
|
90
|
+
readonly protocol?: string | null | undefined;
|
|
91
|
+
/** The `Accept` the request sent. */
|
|
92
|
+
readonly accept?: string | null | undefined;
|
|
93
|
+
/** `Sec-Fetch-Site`, `-Mode` and `-Dest`, which a browser sends and a programmatic fetcher does not. */
|
|
94
|
+
readonly fetchMetadata?: {
|
|
95
|
+
readonly site: string;
|
|
96
|
+
readonly mode: string;
|
|
97
|
+
readonly dest: string;
|
|
98
|
+
} | null | undefined;
|
|
99
|
+
/** What the network said of the client, where the platform tells it: a feature, never a key. */
|
|
100
|
+
readonly network?: {
|
|
101
|
+
readonly asn: number | null;
|
|
102
|
+
readonly country: string | null;
|
|
103
|
+
readonly ja4: string | null;
|
|
104
|
+
} | null | undefined;
|
|
105
|
+
/** A Web Bot Auth signature: the agent URL it named, its key id, and what became of the check. */
|
|
106
|
+
readonly signature?: {
|
|
107
|
+
readonly agent: string;
|
|
108
|
+
readonly keyId: string | null;
|
|
109
|
+
readonly outcome: SignatureOutcome;
|
|
110
|
+
} | null | undefined;
|
|
111
|
+
/** A bot the platform verified against its own directory. */
|
|
112
|
+
readonly verifiedBot?: {
|
|
113
|
+
readonly category: string;
|
|
114
|
+
readonly name: string | null;
|
|
115
|
+
} | null | undefined;
|
|
116
|
+
};
|
|
117
|
+
/** A verified identity, its ids keyed hashes. */
|
|
118
|
+
readonly principal: {
|
|
119
|
+
readonly kind: PrincipalKind;
|
|
120
|
+
readonly id: string;
|
|
121
|
+
readonly actingUserId: string | null;
|
|
122
|
+
} | null;
|
|
123
|
+
readonly registration: {
|
|
124
|
+
readonly id: string;
|
|
125
|
+
readonly phase: RegistrationPhase;
|
|
126
|
+
readonly claimedBy: string | null;
|
|
127
|
+
} | null;
|
|
128
|
+
readonly markers: {
|
|
129
|
+
/** Markers planted in this step's response. */
|
|
130
|
+
readonly served: {
|
|
131
|
+
readonly value: string;
|
|
132
|
+
readonly durable: boolean;
|
|
133
|
+
}[];
|
|
134
|
+
/** Marker strings found in this step's request, as received. */
|
|
135
|
+
readonly seen: string[];
|
|
136
|
+
};
|
|
137
|
+
/** What was hashed or dropped here, and why. */
|
|
138
|
+
readonly redactions: {
|
|
139
|
+
readonly field: string;
|
|
140
|
+
readonly reason: string;
|
|
141
|
+
}[];
|
|
142
|
+
}
|
|
143
|
+
/** The capture code that sent a call, and the surfaces it is set up to capture. */
|
|
144
|
+
export interface Component {
|
|
145
|
+
readonly name: string;
|
|
146
|
+
readonly version: string;
|
|
147
|
+
readonly surfaces: readonly Surface[];
|
|
148
|
+
/**
|
|
149
|
+
* The id of the workspace hash key it hashes with (`hashKeyIdOf`); absent
|
|
150
|
+
* for a component that hashes nothing. The collector refuses an event
|
|
151
|
+
* carrying a hashed value in a call that names no key.
|
|
152
|
+
*/
|
|
153
|
+
readonly hashKeyId?: string;
|
|
154
|
+
}
|