@atcx/contract 7.6.0 → 7.7.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/README.md +7 -5
- package/dist/daemon-contract.d.ts +1 -0
- package/dist/daemon-features.d.ts +1 -1
- package/dist/gateway-paths.d.ts +22 -0
- package/dist/gateway-registry-schema.d.ts +11 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +88 -7
- package/dist/max-events-cursor-bytes.d.ts +1 -0
- package/dist/max-registry-daemons.d.ts +1 -0
- package/dist/request-param-schemas.d.ts +1 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -3,12 +3,12 @@
|
|
|
3
3
|
|
|
4
4
|
<p>
|
|
5
5
|
<a href="https://www.npmjs.com/package/@atcx/contract"><img src="https://img.shields.io/npm/v/@atcx/contract" alt="npm version"></a>
|
|
6
|
-
<a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.
|
|
6
|
+
<a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.7.1/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
|
|
7
7
|
</p>
|
|
8
8
|
|
|
9
9
|
<p>
|
|
10
|
-
<a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.
|
|
11
|
-
<a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.
|
|
10
|
+
<a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.7.1/docs/architecture/protocol/contract.md">The published contract</a> •
|
|
11
|
+
<a href="https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.7.1/docs/architecture/protocol/protocol.md">The client protocol</a>
|
|
12
12
|
</p>
|
|
13
13
|
</div>
|
|
14
14
|
|
|
@@ -46,15 +46,17 @@ bun add -d @opentelemetry/api
|
|
|
46
46
|
for the session record a session's helpers read.
|
|
47
47
|
- **Checking a daemon.** `checkDaemon` compares the major version in the hello answer with the
|
|
48
48
|
contract's, and lists the features that differ.
|
|
49
|
+
- **The gateway.** `GATEWAY_PATHS`, the routes atc-gateway serves grouped as browser, machine and
|
|
50
|
+
probe paths, and `GATEWAY_REGISTRY_SCHEMA`, the rules of the gateway's registry file.
|
|
49
51
|
- **The light entry.** `@atcx/contract/light` holds the session environment names, the state paths
|
|
50
52
|
and the error codes without the request contract, for a process that starts once per event.
|
|
51
53
|
|
|
52
54
|
## Configuration
|
|
53
55
|
|
|
54
56
|
`CONFIG_FILE_SCHEMA` parses the top-level keys of atc's `config.json`, and the
|
|
55
|
-
[configuration guide](https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.
|
|
57
|
+
[configuration guide](https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.7.1/docs/guides/configuration.md) describes each key.
|
|
56
58
|
|
|
57
59
|
## Documentation
|
|
58
60
|
|
|
59
|
-
[The published contract](https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.
|
|
61
|
+
[The published contract](https://github.com/zgeoff/atc/blob/%40zgeoff%2Fatc%407.7.1/docs/architecture/protocol/contract.md) covers what the package holds
|
|
60
62
|
and how its version moves with atc's.
|
|
@@ -5,6 +5,7 @@ export declare const DAEMON_CONTRACT: {
|
|
|
5
5
|
client: z.ZodPreprocess<z.ZodDefault<z.ZodString>, unknown>;
|
|
6
6
|
protocol: z.ZodOptional<z.ZodNumber>;
|
|
7
7
|
principal: z.ZodOptional<z.ZodString>;
|
|
8
|
+
viewer: z.ZodOptional<z.ZodString>;
|
|
8
9
|
session: z.ZodPreprocess<z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./session-id.js").SessionID, string>>>, unknown>;
|
|
9
10
|
}, z.core.$strip>, z.ZodObject<{
|
|
10
11
|
daemon: z.ZodString;
|
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export declare const DAEMON_FEATURES: readonly ['events.read.from-start'];
|
|
1
|
+
export declare const DAEMON_FEATURES: readonly ['events.read.from-start', 'daemon.hello.viewer'];
|
|
2
2
|
export type DaemonFeature = (typeof DAEMON_FEATURES)[number];
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
export declare const GATEWAY_PATHS: {
|
|
2
|
+
readonly browser: {
|
|
3
|
+
readonly authorize: '/oauth2/authorize';
|
|
4
|
+
readonly login: '/login';
|
|
5
|
+
readonly enroll: '/enroll';
|
|
6
|
+
readonly consent: '/consent';
|
|
7
|
+
readonly error: '/error';
|
|
8
|
+
};
|
|
9
|
+
readonly machine: {
|
|
10
|
+
readonly mcp: '/mcp';
|
|
11
|
+
readonly root: '/';
|
|
12
|
+
readonly token: '/oauth2/token';
|
|
13
|
+
readonly revoke: '/oauth2/revoke';
|
|
14
|
+
readonly authorizationServerMetadata: '/.well-known/oauth-authorization-server';
|
|
15
|
+
readonly resourceMetadata: '/.well-known/oauth-protected-resource';
|
|
16
|
+
readonly mcpResourceMetadata: '/.well-known/oauth-protected-resource/mcp';
|
|
17
|
+
};
|
|
18
|
+
readonly probes: {
|
|
19
|
+
readonly health: '/healthz';
|
|
20
|
+
readonly ready: '/readyz';
|
|
21
|
+
};
|
|
22
|
+
};
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
export declare const GATEWAY_REGISTRY_SCHEMA: z.ZodObject<{
|
|
3
|
+
daemons: z.ZodRecord<z.ZodString, z.ZodObject<{
|
|
4
|
+
address: z.ZodPipe<z.ZodString, z.ZodTransform<{
|
|
5
|
+
host: string;
|
|
6
|
+
port: number;
|
|
7
|
+
}, string>>;
|
|
8
|
+
daemonID: z.ZodString;
|
|
9
|
+
}, z.core.$strip>>;
|
|
10
|
+
defaultDaemon: z.ZodString;
|
|
11
|
+
}, z.core.$strip>;
|
package/dist/index.d.ts
CHANGED
|
@@ -13,11 +13,15 @@ export * from './events-page.js';
|
|
|
13
13
|
export type * from './daemon-id.js';
|
|
14
14
|
export * from './fleet-entry-view.js';
|
|
15
15
|
export * from './fleet-event.js';
|
|
16
|
+
export * from './gateway-paths.js';
|
|
17
|
+
export * from './gateway-registry-schema.js';
|
|
16
18
|
export * from './git-probe-result.js';
|
|
17
19
|
export * from './git-ref.js';
|
|
18
20
|
export * from './grant-scope.js';
|
|
19
21
|
export * from './hello-result.js';
|
|
20
22
|
export * from './light/index.js';
|
|
23
|
+
export * from './max-events-cursor-bytes.js';
|
|
24
|
+
export * from './max-registry-daemons.js';
|
|
21
25
|
export * from './menu-view.js';
|
|
22
26
|
export * from './message-answer.js';
|
|
23
27
|
export type * from './message-id.js';
|
package/dist/index.js
CHANGED
|
@@ -110,10 +110,10 @@ var ANSWER_VIEW_SCHEMA = z4.object({
|
|
|
110
110
|
complete: z4.boolean()
|
|
111
111
|
});
|
|
112
112
|
// packages/contract/src/contract-version.ts
|
|
113
|
-
var CONTRACT_VERSION = "7.
|
|
113
|
+
var CONTRACT_VERSION = "7.7.1";
|
|
114
114
|
|
|
115
115
|
// packages/contract/src/daemon-features.ts
|
|
116
|
-
var DAEMON_FEATURES = ["events.read.from-start"];
|
|
116
|
+
var DAEMON_FEATURES = ["events.read.from-start", "daemon.hello.viewer"];
|
|
117
117
|
|
|
118
118
|
// packages/contract/src/check-daemon.ts
|
|
119
119
|
function checkDaemon(hello, contractVersion = CONTRACT_VERSION) {
|
|
@@ -694,6 +694,7 @@ var REQUEST_PARAM_SCHEMAS = {
|
|
|
694
694
|
client: buildDefaultedString("unknown client"),
|
|
695
695
|
protocol: z31.number({ error: "daemon.hello protocol must be a number" }).optional(),
|
|
696
696
|
principal: z31.string({ error: "daemon.hello principal must be a non-empty string" }).min(1, "daemon.hello principal must be a non-empty string").optional(),
|
|
697
|
+
viewer: z31.string({ error: "daemon.hello viewer must be a non-empty string" }).min(1, "daemon.hello viewer must be a non-empty string").optional(),
|
|
697
698
|
session: z31.preprocess((input) => typeof input === "string" && input !== "" ? input : undefined, z31.string().transform(toSessionID).optional())
|
|
698
699
|
}),
|
|
699
700
|
"daemon.ping": z31.object({}),
|
|
@@ -1034,6 +1035,82 @@ var DAEMON_CONTRACT = {
|
|
|
1034
1035
|
get: base.meta(READ).input(PARAMS["answer.get"]).output(ANSWER_VIEW_SCHEMA)
|
|
1035
1036
|
}
|
|
1036
1037
|
};
|
|
1038
|
+
// packages/contract/src/gateway-paths.ts
|
|
1039
|
+
var GATEWAY_PATHS = {
|
|
1040
|
+
browser: {
|
|
1041
|
+
authorize: "/oauth2/authorize",
|
|
1042
|
+
login: "/login",
|
|
1043
|
+
enroll: "/enroll",
|
|
1044
|
+
consent: "/consent",
|
|
1045
|
+
error: "/error"
|
|
1046
|
+
},
|
|
1047
|
+
machine: {
|
|
1048
|
+
mcp: "/mcp",
|
|
1049
|
+
root: "/",
|
|
1050
|
+
token: "/oauth2/token",
|
|
1051
|
+
revoke: "/oauth2/revoke",
|
|
1052
|
+
authorizationServerMetadata: "/.well-known/oauth-authorization-server",
|
|
1053
|
+
resourceMetadata: "/.well-known/oauth-protected-resource",
|
|
1054
|
+
mcpResourceMetadata: "/.well-known/oauth-protected-resource/mcp"
|
|
1055
|
+
},
|
|
1056
|
+
probes: {
|
|
1057
|
+
health: "/healthz",
|
|
1058
|
+
ready: "/readyz"
|
|
1059
|
+
}
|
|
1060
|
+
};
|
|
1061
|
+
// packages/contract/src/gateway-registry-schema.ts
|
|
1062
|
+
import { z as z38 } from "zod";
|
|
1063
|
+
|
|
1064
|
+
// packages/contract/src/max-events-cursor-bytes.ts
|
|
1065
|
+
var MAX_EVENTS_CURSOR_BYTES = 4096;
|
|
1066
|
+
|
|
1067
|
+
// packages/contract/src/max-registry-daemons.ts
|
|
1068
|
+
var MAX_REGISTRY_DAEMONS = 36;
|
|
1069
|
+
|
|
1070
|
+
// packages/contract/src/gateway-registry-schema.ts
|
|
1071
|
+
var DAEMON_NAME_PATTERN = /^[a-z][a-z0-9-]{0,30}$/u;
|
|
1072
|
+
var ADDRESS_PATTERN = /^(?:\[(?<v6>[^\]]+)\]|(?<host>[^:[\]]+)):(?<port>\d{1,5})$/u;
|
|
1073
|
+
var ADDRESS_MESSAGE = "needs an address of <host>:<port> with a port from 1 to 65535";
|
|
1074
|
+
var ADDRESS_SCHEMA = z38.string({ error: ADDRESS_MESSAGE }).transform((raw, ctx) => {
|
|
1075
|
+
const groups = ADDRESS_PATTERN.exec(raw)?.groups;
|
|
1076
|
+
const host = groups?.["v6"] ?? groups?.["host"];
|
|
1077
|
+
const port = Number(groups?.["port"]);
|
|
1078
|
+
if (host === undefined || !Number.isInteger(port) || port < 1 || port > 65535) {
|
|
1079
|
+
ctx.issues.push({ code: "custom", message: ADDRESS_MESSAGE, input: raw });
|
|
1080
|
+
return z38.NEVER;
|
|
1081
|
+
}
|
|
1082
|
+
return { host, port };
|
|
1083
|
+
});
|
|
1084
|
+
var DAEMON_ID_MESSAGE = "needs the daemonID that atc daemon id prints on its host";
|
|
1085
|
+
var DAEMON_ID_SCHEMA2 = z38.string({ error: DAEMON_ID_MESSAGE }).regex(/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/u, DAEMON_ID_MESSAGE);
|
|
1086
|
+
var DAEMON_SCHEMA = z38.object({ address: ADDRESS_SCHEMA, daemonID: DAEMON_ID_SCHEMA2 }, { error: "must be an object with address and daemonID" });
|
|
1087
|
+
var GATEWAY_REGISTRY_SCHEMA = z38.object({
|
|
1088
|
+
daemons: z38.record(z38.string().regex(DAEMON_NAME_PATTERN), DAEMON_SCHEMA, {
|
|
1089
|
+
error: (issue) => issue.code === "invalid_key" ? `must match ${DAEMON_NAME_PATTERN.source}` : "the registry must be an object whose daemons is an object"
|
|
1090
|
+
}),
|
|
1091
|
+
defaultDaemon: z38.string({
|
|
1092
|
+
error: "defaultDaemon is required and must name a daemon in the registry"
|
|
1093
|
+
})
|
|
1094
|
+
}, { error: "the registry must be an object whose daemons is an object" }).superRefine((registry, ctx) => {
|
|
1095
|
+
const count = Object.keys(registry.daemons).length;
|
|
1096
|
+
if (count === 0) {
|
|
1097
|
+
ctx.addIssue({ code: "custom", path: ["daemons"], message: "the registry lists no daemon" });
|
|
1098
|
+
}
|
|
1099
|
+
if (count > MAX_REGISTRY_DAEMONS) {
|
|
1100
|
+
ctx.addIssue({
|
|
1101
|
+
code: "custom",
|
|
1102
|
+
path: ["daemons"],
|
|
1103
|
+
message: `the registry lists ${count} daemons, over the limit of ${MAX_REGISTRY_DAEMONS}, the most whose events cursor fits ${MAX_EVENTS_CURSOR_BYTES} bytes`
|
|
1104
|
+
});
|
|
1105
|
+
}
|
|
1106
|
+
if (!Object.hasOwn(registry.daemons, registry.defaultDaemon)) {
|
|
1107
|
+
ctx.addIssue({
|
|
1108
|
+
code: "custom",
|
|
1109
|
+
path: ["defaultDaemon"],
|
|
1110
|
+
message: `defaultDaemon '${registry.defaultDaemon}' is not a daemon in the registry`
|
|
1111
|
+
});
|
|
1112
|
+
}
|
|
1113
|
+
});
|
|
1037
1114
|
// packages/contract/src/light/resolve-atc-paths.ts
|
|
1038
1115
|
import { join as join2 } from "node:path";
|
|
1039
1116
|
|
|
@@ -1076,11 +1153,11 @@ var SESSION_ENV_NAMES = {
|
|
|
1076
1153
|
scopeFile: "AUTO_MODE_SCOPE_FILE"
|
|
1077
1154
|
};
|
|
1078
1155
|
// packages/contract/src/procedure-meta.ts
|
|
1079
|
-
import { z as
|
|
1080
|
-
var PROCEDURE_META_SCHEMA =
|
|
1081
|
-
access:
|
|
1082
|
-
readOnly:
|
|
1083
|
-
keyed:
|
|
1156
|
+
import { z as z39 } from "zod";
|
|
1157
|
+
var PROCEDURE_META_SCHEMA = z39.object({
|
|
1158
|
+
access: z39.enum(["owner", "principal"]),
|
|
1159
|
+
readOnly: z39.boolean(),
|
|
1160
|
+
keyed: z39.boolean()
|
|
1084
1161
|
});
|
|
1085
1162
|
export {
|
|
1086
1163
|
AGENT_ENTRY_SCHEMA,
|
|
@@ -1097,10 +1174,14 @@ export {
|
|
|
1097
1174
|
EVENTS_PAGE_SCHEMA,
|
|
1098
1175
|
FLEET_ENTRY_VIEW_SCHEMA,
|
|
1099
1176
|
FLEET_EVENT_SCHEMA,
|
|
1177
|
+
GATEWAY_PATHS,
|
|
1178
|
+
GATEWAY_REGISTRY_SCHEMA,
|
|
1100
1179
|
GIT_PROBE_RESULT_SCHEMA,
|
|
1101
1180
|
GIT_REF_SCHEMA,
|
|
1102
1181
|
GRANT_SCOPES,
|
|
1103
1182
|
HELLO_RESULT_SCHEMA,
|
|
1183
|
+
MAX_EVENTS_CURSOR_BYTES,
|
|
1184
|
+
MAX_REGISTRY_DAEMONS,
|
|
1104
1185
|
MENU_VIEW_SCHEMA,
|
|
1105
1186
|
MESSAGE_ANSWER_SCHEMA,
|
|
1106
1187
|
MESSAGE_SENDER_SCHEMA,
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare const MAX_EVENTS_CURSOR_BYTES = 4096;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare const MAX_REGISTRY_DAEMONS = 36;
|
|
@@ -22,6 +22,7 @@ export declare const REQUEST_PARAM_SCHEMAS: {
|
|
|
22
22
|
client: z.ZodPreprocess<z.ZodDefault<z.ZodString>, unknown>;
|
|
23
23
|
protocol: z.ZodOptional<z.ZodNumber>;
|
|
24
24
|
principal: z.ZodOptional<z.ZodString>;
|
|
25
|
+
viewer: z.ZodOptional<z.ZodString>;
|
|
25
26
|
session: z.ZodPreprocess<z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./session-id.js").SessionID, string>>>, unknown>;
|
|
26
27
|
}, z.core.$strip>;
|
|
27
28
|
readonly 'daemon.ping': z.ZodObject<{}, z.core.$strip>;
|
package/package.json
CHANGED
|
@@ -18,8 +18,8 @@
|
|
|
18
18
|
"zod": "4.6.6"
|
|
19
19
|
},
|
|
20
20
|
"name": "@atcx/contract",
|
|
21
|
-
"version": "7.
|
|
22
|
-
"description": "atc's public contract: the daemon's request contract, the event, session record, hello and config schemas, the error codes, the session env names, and the
|
|
21
|
+
"version": "7.7.1",
|
|
22
|
+
"description": "atc's public contract: the daemon's request contract, the event, session record, hello and config schemas, the error codes, the session env names, the state paths, and the gateway's routes and registry schema",
|
|
23
23
|
"homepage": "https://github.com/zgeoff/atc/tree/main/packages/contract#readme",
|
|
24
24
|
"bugs": "https://github.com/zgeoff/atc/issues",
|
|
25
25
|
"license": "MIT",
|