@norskvideo/ctl-product-template-schema 0.1.76 → 0.1.78

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.
@@ -0,0 +1,26 @@
1
+ import { type Result } from "@norskvideo/ctl-foundation/browser";
2
+ /** A parsed, known-good managed host-port binding. The single in-memory form of
3
+ * the `spec` grammar `HOST[:CONTAINER][/proto]`. `proto` is closed (bare ports
4
+ * are tcp); `5001` and `5001/tcp` parse to the same value. See CONTEXT.md
5
+ * "Managed host-port binding" and ADR-0003. */
6
+ export interface HostPortSpec {
7
+ host: number;
8
+ container: number;
9
+ proto: "tcp" | "udp";
10
+ }
11
+ /**
12
+ * The single gate for the host-port spec grammar. Everything downstream —
13
+ * validation, the host-socket key, the compose mapping — derives from this one
14
+ * parse, so the grammar has exactly one home. An unparseable or out-of-range
15
+ * spec is a typed error, never a silent passthrough.
16
+ */
17
+ export declare function parseHostPortSpec(spec: string): Result<HostPortSpec, string>;
18
+ /** The `(host port, protocol)` identity — the unit of host-socket exclusivity.
19
+ * Conflict detection keys on this regardless of container side or target service. */
20
+ export declare function hostSocketKey(p: HostPortSpec): string;
21
+ /** Render to a docker-compose port mapping: always explicit `HOST:CONTAINER`,
22
+ * with a `/udp` suffix only (tcp is compose's default, so it's omitted). */
23
+ export declare function toComposeMapping(p: HostPortSpec): string;
24
+ /** Render to the canonical spec string — the only origin of spec strings.
25
+ * Drops a redundant same-port container and a redundant `/tcp`. */
26
+ export declare function renderSpec(p: HostPortSpec): string;
@@ -0,0 +1,50 @@
1
+ import { err, ok } from "@norskvideo/ctl-foundation/browser";
2
+ function parsePort(s) {
3
+ if (!/^\d+$/.test(s))
4
+ return null;
5
+ const n = Number(s);
6
+ return n >= 1 && n <= 65535 ? n : null;
7
+ }
8
+ /**
9
+ * The single gate for the host-port spec grammar. Everything downstream —
10
+ * validation, the host-socket key, the compose mapping — derives from this one
11
+ * parse, so the grammar has exactly one home. An unparseable or out-of-range
12
+ * spec is a typed error, never a silent passthrough.
13
+ */
14
+ export function parseHostPortSpec(spec) {
15
+ const trimmed = spec.trim();
16
+ const slash = trimmed.indexOf("/");
17
+ const portPart = slash === -1 ? trimmed : trimmed.slice(0, slash);
18
+ const protoPart = slash === -1 ? "tcp" : trimmed.slice(slash + 1);
19
+ if (protoPart !== "tcp" && protoPart !== "udp") {
20
+ return err(`Invalid protocol in '${spec}' (expected tcp or udp)`);
21
+ }
22
+ const sides = portPart.split(":");
23
+ if (sides.length > 2)
24
+ return err(`Invalid host-port spec '${spec}'`);
25
+ const host = parsePort(sides[0]);
26
+ if (host === null)
27
+ return err(`Invalid host port in '${spec}' (expected 1-65535)`);
28
+ const container = sides.length === 2 ? parsePort(sides[1]) : host;
29
+ if (container === null)
30
+ return err(`Invalid container port in '${spec}' (expected 1-65535)`);
31
+ return ok({ host, container, proto: protoPart });
32
+ }
33
+ /** The `(host port, protocol)` identity — the unit of host-socket exclusivity.
34
+ * Conflict detection keys on this regardless of container side or target service. */
35
+ export function hostSocketKey(p) {
36
+ return `${p.host}/${p.proto}`;
37
+ }
38
+ /** Render to a docker-compose port mapping: always explicit `HOST:CONTAINER`,
39
+ * with a `/udp` suffix only (tcp is compose's default, so it's omitted). */
40
+ export function toComposeMapping(p) {
41
+ const proto = p.proto === "udp" ? "/udp" : "";
42
+ return `${p.host}:${p.container}${proto}`;
43
+ }
44
+ /** Render to the canonical spec string — the only origin of spec strings.
45
+ * Drops a redundant same-port container and a redundant `/tcp`. */
46
+ export function renderSpec(p) {
47
+ const container = p.container === p.host ? "" : `:${p.container}`;
48
+ const proto = p.proto === "udp" ? "/udp" : "";
49
+ return `${p.host}${container}${proto}`;
50
+ }
package/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { z } from "zod";
2
+ import { LISTENER_KINDS } from "./port-bindings.js";
2
3
  export declare const ProductTemplateTargetSchema: z.ZodEnum<{
3
4
  "docker-compose": "docker-compose";
4
5
  }>;
@@ -45,7 +46,7 @@ export declare const ProductTemplateAdvancedSchema: z.ZodObject<{
45
46
  default: z.ZodOptional<z.ZodString>;
46
47
  }, z.core.$strip>>;
47
48
  }, z.core.$strip>;
48
- export declare const LISTENER_KINDS: readonly ["http", "webrtc", "moq", "srt", "rist", "udp-ts", "rtmp", "tcp", "udp", "grpc"];
49
+ export { LISTENER_KINDS };
49
50
  export declare const ProductTemplateListenerSchema: z.ZodObject<{
50
51
  kind: z.ZodEnum<{
51
52
  tcp: "tcp";
package/index.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { z } from "zod";
2
2
  import { ProductTemplateInterfaceSchema } from "./interfaces.js";
3
3
  import { ProductTemplateLogsSchema } from "./logs.js";
4
+ import { LISTENER_ID_PATTERN, LISTENER_KINDS } from "./port-bindings.js";
4
5
  // ProductTemplate format v1. A product template is a tar file at the wire; the schemas
5
6
  // below describe its parts before packing and how the runner validates
6
7
  // the unpacked tar.
@@ -266,15 +267,15 @@ export const ProductTemplateAdvancedSchema = z
266
267
  // re-supplies the recorded number, so an opened instance keeps its port.
267
268
  // Distinct from `advanced.hostPorts` (operator-typed extra bindings with no
268
269
  // parameter linkage).
269
- // The listener kinds of the addressing document (norsk-contracts, src/addressing/schema.ts
270
- // ListenerKind). Kept in step by a test in the backend, which has the contract's copy.
271
- export const LISTENER_KINDS = ["http", "webrtc", "moq", "srt", "rist", "udp-ts", "rtmp", "tcp", "udp", "grpc"];
270
+ // The listener kinds of the addressing document live in port-bindings.ts, with
271
+ // the transport and default port of each.
272
+ export { LISTENER_KINDS };
272
273
  export const ProductTemplateListenerSchema = z
273
274
  .object({
274
275
  kind: z.enum(LISTENER_KINDS),
275
276
  id: z
276
277
  .string()
277
- .regex(/^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/, "a DNS label: a-z, 0-9 and '-'")
278
+ .regex(LISTENER_ID_PATTERN, "a DNS label: a-z, 0-9 and '-'")
278
279
  .optional()
279
280
  .meta({ description: "The listener's name in the document; omitted = the kind. Needed only for two of a kind." }),
280
281
  })
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@norskvideo/ctl-product-template-schema",
3
- "version": "0.1.76",
3
+ "version": "0.1.78",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
@@ -47,6 +47,14 @@
47
47
  "./product-channels": {
48
48
  "types": "./product-channels.d.ts",
49
49
  "default": "./product-channels.js"
50
+ },
51
+ "./host-port-spec": {
52
+ "types": "./host-port-spec.d.ts",
53
+ "default": "./host-port-spec.js"
54
+ },
55
+ "./port-bindings": {
56
+ "types": "./port-bindings.d.ts",
57
+ "default": "./port-bindings.js"
50
58
  }
51
59
  },
52
60
  "main": "./index.js",
@@ -0,0 +1,45 @@
1
+ import { type Result } from "@norskvideo/ctl-foundation/browser";
2
+ export declare const LISTENER_KINDS: readonly ["http", "webrtc", "moq", "srt", "rist", "udp-ts", "rtmp", "tcp", "udp", "grpc"];
3
+ export type ListenerKind = (typeof LISTENER_KINDS)[number];
4
+ export declare const LISTENER_TRANSPORT: Readonly<Record<ListenerKind, "tcp" | "udp">>;
5
+ export declare const LISTENER_DEFAULT_PORT: Readonly<Partial<Record<ListenerKind, number>>>;
6
+ /** A listener's name in the addressing document: a DNS label. */
7
+ export declare const LISTENER_ID_PATTERN: RegExp;
8
+ export declare function isListenerKind(value: string): value is ListenerKind;
9
+ /** What listens on a port: its kind in the addressing document, and its name
10
+ * there when the default will not do (two of a kind). */
11
+ export interface PortListener {
12
+ kind: ListenerKind;
13
+ id?: string;
14
+ }
15
+ /** One port and what listens on it. `port` is the listener's own, inside the
16
+ * container; `hostPort` is given only when the host publishes it on another
17
+ * number; `service` only when it is not the media service. */
18
+ export interface PortBinding {
19
+ listener: PortListener;
20
+ port: number;
21
+ hostPort?: number;
22
+ service?: string;
23
+ }
24
+ /** A managed host-port binding as it is sent and stored. */
25
+ export interface HostPortBinding {
26
+ spec: string;
27
+ service?: string;
28
+ listener?: PortListener;
29
+ }
30
+ /** The wire form of a binding. The protocol is the kind's, never chosen. A
31
+ * generic tcp/udp binding with no name carries no listener: its spec already
32
+ * says all of it, and it is then the binding every older reader knows. */
33
+ export declare function portBindingToHostPort(binding: PortBinding): HostPortBinding;
34
+ /** The structured form of a wire binding. One that names no listener is the
35
+ * generic kind of its protocol, which is all anyone said about it. */
36
+ export declare function hostPortToPortBinding(hostPort: HostPortBinding): Result<PortBinding, string>;
37
+ /** Why a binding's listener cannot be what speaks on its spec, or undefined.
38
+ * A spec that does not parse is not this function's to report. */
39
+ export declare function listenerSpecError(hostPort: HostPortBinding): string | undefined;
40
+ /** Split one host-port token. Nothing is checked here beyond recognising the
41
+ * prefix: the spec goes to parseHostPortSpec and the listener to
42
+ * listenerSpecError, which is where a wrong one gets its message. */
43
+ export declare function parseHostPortToken(token: string): HostPortBinding;
44
+ /** A binding back in its text form, the inverse of parseHostPortToken. */
45
+ export declare function formatHostPortToken(hostPort: HostPortBinding): string;
@@ -0,0 +1,131 @@
1
+ // One way to say "this port, and what listens on it", wherever a port is
2
+ // declared: an operator's extra host ports today, a product template's own
3
+ // ports next. Zod-free, so a form in the browser can import it.
4
+ //
5
+ // A PortBinding is the structured form. A host-port binding on the wire stays
6
+ // what ADR-0003 made it, `{ spec, service? }`, and gains an optional
7
+ // `listener`; the functions here are the only crossing between the two, and
8
+ // the only place a listener kind turns into tcp or udp.
9
+ import { err, ok } from "@norskvideo/ctl-foundation/browser";
10
+ import { parseHostPortSpec, renderSpec } from "./host-port-spec.js";
11
+ // The listener kinds of the addressing document (norsk-contracts,
12
+ // src/addressing/schema.ts ListenerKind), with the transport and default port
13
+ // its catalogue gives each. Kept in step by a test in the norsk-ctl backend,
14
+ // which has the contract's copy.
15
+ export const LISTENER_KINDS = ["http", "webrtc", "moq", "srt", "rist", "udp-ts", "rtmp", "tcp", "udp", "grpc"];
16
+ export const LISTENER_TRANSPORT = {
17
+ http: "tcp",
18
+ webrtc: "udp",
19
+ moq: "udp",
20
+ srt: "udp",
21
+ rist: "udp",
22
+ "udp-ts": "udp",
23
+ rtmp: "tcp",
24
+ tcp: "tcp",
25
+ udp: "udp",
26
+ grpc: "tcp",
27
+ };
28
+ export const LISTENER_DEFAULT_PORT = {
29
+ http: 8080,
30
+ webrtc: 30500,
31
+ moq: 4443,
32
+ srt: 5001,
33
+ "udp-ts": 5001,
34
+ rtmp: 1935,
35
+ grpc: 6790,
36
+ };
37
+ /** A listener's name in the addressing document: a DNS label. */
38
+ export const LISTENER_ID_PATTERN = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
39
+ export function isListenerKind(value) {
40
+ return LISTENER_KINDS.includes(value);
41
+ }
42
+ /** The wire form of a binding. The protocol is the kind's, never chosen. A
43
+ * generic tcp/udp binding with no name carries no listener: its spec already
44
+ * says all of it, and it is then the binding every older reader knows. */
45
+ export function portBindingToHostPort(binding) {
46
+ const { kind, id } = binding.listener;
47
+ const generic = (kind === "tcp" || kind === "udp") && !id;
48
+ return {
49
+ spec: renderSpec({
50
+ host: binding.hostPort ?? binding.port,
51
+ container: binding.port,
52
+ proto: LISTENER_TRANSPORT[kind],
53
+ }),
54
+ ...(binding.service ? { service: binding.service } : {}),
55
+ ...(generic ? {} : { listener: { kind, ...(id ? { id } : {}) } }),
56
+ };
57
+ }
58
+ /** The structured form of a wire binding. One that names no listener is the
59
+ * generic kind of its protocol, which is all anyone said about it. */
60
+ export function hostPortToPortBinding(hostPort) {
61
+ const parsed = parseHostPortSpec(hostPort.spec);
62
+ if (parsed.status !== "ok")
63
+ return err(parsed.error);
64
+ const mismatch = listenerSpecError(hostPort);
65
+ if (mismatch)
66
+ return err(mismatch);
67
+ const { host, container, proto } = parsed.value;
68
+ return ok({
69
+ listener: hostPort.listener
70
+ ? { kind: hostPort.listener.kind, ...(hostPort.listener.id ? { id: hostPort.listener.id } : {}) }
71
+ : { kind: proto },
72
+ port: container,
73
+ ...(host !== container ? { hostPort: host } : {}),
74
+ ...(hostPort.service ? { service: hostPort.service } : {}),
75
+ });
76
+ }
77
+ /** Why a binding's listener cannot be what speaks on its spec, or undefined.
78
+ * A spec that does not parse is not this function's to report. */
79
+ export function listenerSpecError(hostPort) {
80
+ const listener = hostPort.listener;
81
+ if (!listener)
82
+ return undefined;
83
+ if (!isListenerKind(listener.kind))
84
+ return `Unknown listener kind '${String(listener.kind)}' on '${hostPort.spec}'`;
85
+ if (listener.id !== undefined && !LISTENER_ID_PATTERN.test(listener.id)) {
86
+ return `Invalid listener name '${listener.id}' on '${hostPort.spec}' (a-z, 0-9 and '-')`;
87
+ }
88
+ const parsed = parseHostPortSpec(hostPort.spec);
89
+ if (parsed.status !== "ok")
90
+ return undefined;
91
+ const transport = LISTENER_TRANSPORT[listener.kind];
92
+ return parsed.value.proto === transport
93
+ ? undefined
94
+ : `A ${listener.kind} listener is ${transport}, but '${hostPort.spec}' is ${parsed.value.proto}`;
95
+ }
96
+ // ── The text form ──────────────────────────────────────────────────────────
97
+ // `[KIND[=NAME]:]SPEC[@service]`, for a CLI flag and for a product template's
98
+ // default host ports. Like `@service`, the `KIND:` prefix is a text-input
99
+ // concern outside the spec grammar: `srt:5001` is the spec `5001/udp` with an
100
+ // srt listener. A token with no prefix is exactly what it was before.
101
+ const KIND_PREFIX = /^([a-z][a-z0-9-]*)(?:=([^:]*))?:(.*)$/;
102
+ /** Split one host-port token. Nothing is checked here beyond recognising the
103
+ * prefix: the spec goes to parseHostPortSpec and the listener to
104
+ * listenerSpecError, which is where a wrong one gets its message. */
105
+ export function parseHostPortToken(token) {
106
+ const at = token.indexOf("@");
107
+ const head = (at === -1 ? token : token.slice(0, at)).trim();
108
+ const service = at === -1 ? undefined : token.slice(at + 1).trim();
109
+ const withService = (binding) => service === undefined ? binding : { ...binding, service };
110
+ const prefixed = KIND_PREFIX.exec(head);
111
+ if (!prefixed || !isListenerKind(prefixed[1]))
112
+ return withService({ spec: head });
113
+ const kind = prefixed[1];
114
+ const id = prefixed[2];
115
+ const rest = prefixed[3].trim();
116
+ // A bare port is tcp to the spec grammar, so a udp kind has to say so.
117
+ const spec = rest.includes("/") || LISTENER_TRANSPORT[kind] === "tcp" ? rest : `${rest}/udp`;
118
+ return withService({ spec, listener: { kind, ...(id !== undefined ? { id: id.trim() } : {}) } });
119
+ }
120
+ /** A binding back in its text form, the inverse of parseHostPortToken. */
121
+ export function formatHostPortToken(hostPort) {
122
+ const service = hostPort.service ? `@${hostPort.service}` : "";
123
+ const listener = hostPort.listener;
124
+ if (!listener)
125
+ return `${hostPort.spec}${service}`;
126
+ const name = listener.id ? `=${listener.id}` : "";
127
+ // The kind says the protocol, so the spec need not repeat it.
128
+ const suffix = `/${LISTENER_TRANSPORT[listener.kind]}`;
129
+ const spec = hostPort.spec.endsWith(suffix) ? hostPort.spec.slice(0, -suffix.length) : hostPort.spec;
130
+ return `${listener.kind}${name}:${spec}${service}`;
131
+ }
@@ -2,6 +2,7 @@ import { type SecretResolver } from "./resolver.js";
2
2
  export { isSecretReference, parseSecretReference, SECRET_PLACEHOLDER, SECRET_REFERENCE_PREFIX, type SecretReference, secretReference, } from "../secret-references.js";
3
3
  export { activeSecretsProfile, type LoadSecretProvidersOptions, loadSecretProviders, PRODUCTION_SECRETS_PROFILE, RESERVED_PROVIDER_NAMES, SECRETS_PROFILE_ENV, SecretProfileSchema, type SecretProvidersConfig, SecretProvidersConfigSchema, secretsProfileNotice, } from "./config.js";
4
4
  export { type DelegateOptions, delegateResolver } from "./delegate.js";
5
+ export { INVALID_SECRET_NAME_MESSAGE, MAX_SECRET_VALUE_BYTES, validSecretName } from "./names.js";
5
6
  export { deobfuscate, isObfuscated, OBFUSCATED_PREFIX, obfuscate } from "./obfuscation.js";
6
7
  export type { SecretProvider, SecretProviders, SecretResolutionError } from "./provider.js";
7
8
  export { type AwsSecretProviderOptions, awsSecretProvider } from "./providers/aws.js";
package/secrets/index.js CHANGED
@@ -12,6 +12,7 @@ import { SECRETS_TOKEN_ENV, SECRETS_URL_ENV } from "./wire.js";
12
12
  export { isSecretReference, parseSecretReference, SECRET_PLACEHOLDER, SECRET_REFERENCE_PREFIX, secretReference, } from "../secret-references.js";
13
13
  export { activeSecretsProfile, loadSecretProviders, PRODUCTION_SECRETS_PROFILE, RESERVED_PROVIDER_NAMES, SECRETS_PROFILE_ENV, SecretProfileSchema, SecretProvidersConfigSchema, secretsProfileNotice, } from "./config.js";
14
14
  export { delegateResolver } from "./delegate.js";
15
+ export { INVALID_SECRET_NAME_MESSAGE, MAX_SECRET_VALUE_BYTES, validSecretName } from "./names.js";
15
16
  export { deobfuscate, isObfuscated, OBFUSCATED_PREFIX, obfuscate } from "./obfuscation.js";
16
17
  export { awsSecretProvider } from "./providers/aws.js";
17
18
  export { envSecretProvider } from "./providers/env.js";
@@ -0,0 +1,6 @@
1
+ /** The largest value a `norsk` store takes. */
2
+ export declare const MAX_SECRET_VALUE_BYTES: number;
3
+ /** Path-like: `/`-separated segments, so a tenant's secrets can sit under
4
+ * `tenants/<id>/` (the tenant policy's rule), and none of them `.` or `..`. */
5
+ export declare function validSecretName(name: string): boolean;
6
+ export declare const INVALID_SECRET_NAME_MESSAGE: string;
@@ -0,0 +1,18 @@
1
+ // A `norsk` secret's name, shared by every store that holds them (norsk-ctl's
2
+ // and norsk-mgr's, RFC 0011 §3.4) so a name one accepts the other does too.
3
+ /** The largest value a `norsk` store takes. */
4
+ export const MAX_SECRET_VALUE_BYTES = 64 * 1024;
5
+ const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
6
+ const MAX_NAME = 256;
7
+ /** The resolve route's own path segment: the guard lets that path through
8
+ * unauthenticated, so no secret may be addressed by it. */
9
+ const RESERVED_NAMES = new Set(["resolve"]);
10
+ /** Path-like: `/`-separated segments, so a tenant's secrets can sit under
11
+ * `tenants/<id>/` (the tenant policy's rule), and none of them `.` or `..`. */
12
+ export function validSecretName(name) {
13
+ if (name.length === 0 || name.length > MAX_NAME || RESERVED_NAMES.has(name))
14
+ return false;
15
+ return name.split("/").every((s) => SEGMENT.test(s) && !/^\.+$/.test(s));
16
+ }
17
+ export const INVALID_SECRET_NAME_MESSAGE = "a secret's name is one or more '/'-separated segments of letters, digits, '.', '_' and '-', " +
18
+ `each starting with a letter or digit, at most ${MAX_NAME} characters, and not 'resolve'`;