@norskvideo/ctl-product-template-schema 0.1.30 → 0.1.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-product-template-schema",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "type": "module",
   "exports": {
     ".": {
@@ -30,6 +30,10 @@
     "./migration-socket": {
       "types": "./migration-socket.d.ts",
       "default": "./migration-socket.js"
+    },
+    "./product-channels": {
+      "types": "./product-channels.d.ts",
+      "default": "./product-channels.js"
     }
   },
   "main": "./index.js",

package/product-channels.d.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+export declare const PRODUCT_CHANNELS_SCHEMA_VERSION = 1;
+/** Public read URL of a product's channels object. */
+export declare function productChannelsUrl(product: string): string;
+/** Write target of a product's channels object. */
+export declare function productChannelsS3Uri(product: string): string;
+export declare const ProductChannelSchema: z.ZodEnum<{
+    nightly: "nightly";
+    rc: "rc";
+    latest: "latest";
+}>;
+export type ProductChannel = z.infer<typeof ProductChannelSchema>;
+export declare const ProductChannelRowSchema: z.ZodObject<{
+    image: z.ZodString;
+    sha: z.ZodString;
+    publishedAt: z.ZodString;
+    runtimeImages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    gate: z.ZodObject<{
+        checks: z.ZodLiteral<"passed">;
+        guides: z.ZodUnion<readonly [z.ZodLiteral<"passed">, z.ZodObject<{
+            skipped: z.ZodString;
+        }, z.core.$loose>]>;
+        run: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+export type ProductChannelRow = z.infer<typeof ProductChannelRowSchema>;
+export declare const ProductChannelsSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    product: z.ZodString;
+    imageRef: z.ZodString;
+    updated: z.ZodString;
+    channels: z.ZodRecord<z.ZodEnum<{
+        nightly: "nightly";
+        rc: "rc";
+        latest: "latest";
+    }> & z.core.$partial, z.ZodObject<{
+        image: z.ZodString;
+        sha: z.ZodString;
+        publishedAt: z.ZodString;
+        runtimeImages: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        gate: z.ZodObject<{
+            checks: z.ZodLiteral<"passed">;
+            guides: z.ZodUnion<readonly [z.ZodLiteral<"passed">, z.ZodObject<{
+                skipped: z.ZodString;
+            }, z.core.$loose>]>;
+            run: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type ProductChannels = z.infer<typeof ProductChannelsSchema>;
+export declare function parseProductChannels(raw: unknown): {
+    ok: true;
+    value: ProductChannels;
+} | {
+    ok: false;
+    error: string;
+};
+/** `current` with `channel` set to `row`; every other channel is kept. */
+export declare function withChannelRow(current: ProductChannels | null, opts: {
+    product: string;
+    imageRef: string;
+    channel: ProductChannel;
+    row: ProductChannelRow;
+    updated: string;
+}): ProductChannels;

package/product-channels.js

@@ -0,0 +1,75 @@
+// Which product image each release channel offers, written by the product's
+// gated publish and read by ctl when it registers the product.
+//
+// One object per product (`products/<name>/channels.json` on the norsk.video
+// bucket), not rows in the shared channel-manifest.json: each product repo's
+// role can then write only its own prefix, and six writers never race a
+// read-modify-write on one object. Only a publish that passed the gate writes a
+// row, so a row means "this image passed checks and the guides" -- the thing a
+// hand-pinned deployment/products.json could never say, and went six weeks
+// stale instead (task 57).
+//
+// Readers ignore fields they do not know: an older ctl reads objects written by
+// newer dev-kits.
+import { z } from "zod";
+export const PRODUCT_CHANNELS_SCHEMA_VERSION = 1;
+const BUCKET = "norsk.video";
+const BUCKET_URL = `https://s3.eu-west-1.amazonaws.com/${BUCKET}`;
+/** A product's licence name, e.g. `norsk-probe`. It names an S3 prefix, so it
+ *  is held to a shape that cannot leave that prefix. */
+const PRODUCT_NAME = /^[a-z0-9][a-z0-9-]*$/;
+function productChannelsKey(product) {
+    if (!PRODUCT_NAME.test(product))
+        throw new Error(`not a product name: ${JSON.stringify(product)}`);
+    return `products/${product}/channels.json`;
+}
+/** Public read URL of a product's channels object. */
+export function productChannelsUrl(product) {
+    return `${BUCKET_URL}/${productChannelsKey(product)}`;
+}
+/** Write target of a product's channels object. */
+export function productChannelsS3Uri(product) {
+    return `s3://${BUCKET}/${productChannelsKey(product)}`;
+}
+export const ProductChannelSchema = z.enum(["nightly", "rc", "latest"]);
+export const ProductChannelRowSchema = z.looseObject({
+    /** The immutable dated tag, `<repo>:<YYYY-MM-DD>-<sha8>` -- never a channel tag. */
+    image: z.string().min(1),
+    /** The product commit the image was built from. */
+    sha: z.string().min(7),
+    publishedAt: z.string().min(1),
+    /** The Norsk and Studio images the product's templates launch (its
+     *  `norsk-ctl.runtime-images` label). */
+    runtimeImages: z.array(z.string()).default([]),
+    gate: z.looseObject({
+        checks: z.literal("passed"),
+        /** `passed`, or skipped by the product's explicit opt-out, with its reason. */
+        guides: z.union([z.literal("passed"), z.looseObject({ skipped: z.string().min(1) })]),
+        /** The run that gated and published this image. */
+        run: z.string().optional(),
+    }),
+});
+export const ProductChannelsSchema = z.looseObject({
+    schemaVersion: z.literal(PRODUCT_CHANNELS_SCHEMA_VERSION),
+    product: z.string().regex(PRODUCT_NAME),
+    imageRef: z.string().min(1),
+    updated: z.string().min(1),
+    channels: z.partialRecord(ProductChannelSchema, ProductChannelRowSchema),
+});
+export function parseProductChannels(raw) {
+    const r = ProductChannelsSchema.safeParse(raw);
+    return r.success ? { ok: true, value: r.data } : { ok: false, error: z.prettifyError(r.error) };
+}
+/** `current` with `channel` set to `row`; every other channel is kept. */
+export function withChannelRow(current, opts) {
+    if (current && (current.product !== opts.product || current.imageRef !== opts.imageRef)) {
+        throw new Error(`channels object belongs to ${current.product} (${current.imageRef}), not ${opts.product} (${opts.imageRef})`);
+    }
+    return {
+        schemaVersion: PRODUCT_CHANNELS_SCHEMA_VERSION,
+        product: opts.product,
+        imageRef: opts.imageRef,
+        updated: opts.updated,
+        channels: { ...(current?.channels ?? {}), [opts.channel]: opts.row },
+    };
+}