@norskvideo/ctl-product-template-schema 0.1.14 → 0.1.16

package/index.d.ts

@@ -3,6 +3,7 @@ export declare const ProductTemplateTargetSchema: z.ZodEnum<{
     "docker-compose": "docker-compose";
 }>;
 export type ProductTemplateTarget = z.infer<typeof ProductTemplateTargetSchema>;
+export declare const RESERVED_INSTANCE_ROUTE_SEGMENTS: readonly ["studio", "media", "visualiser", "uvis", "status", "metrics"];
 export declare const PRODUCT_TEMPLATE_ADVANCED_NETWORK_MODES: readonly ["docker", "hybrid"];
 export declare const ProductTemplateAdvancedSchema: z.ZodObject<{
     networkMode: z.ZodOptional<z.ZodObject<{
@@ -115,6 +116,7 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
             healthy: "healthy";
             never: "never";
         }>>;
+        runtimeReadyPath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     debug: z.ZodOptional<z.ZodObject<{
         studio: z.ZodOptional<z.ZodBoolean>;
@@ -122,6 +124,13 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
     }, z.core.$strip>>;
     proxy: z.ZodOptional<z.ZodObject<{
         expose: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        routes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            segment: z.ZodString;
+            service: z.ZodString;
+            port: z.ZodOptional<z.ZodNumber>;
+            websocket: z.ZodOptional<z.ZodBoolean>;
+            auth: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>;
     requiresWorkingDirectory: z.ZodOptional<z.ZodBoolean>;
     sideload: z.ZodOptional<z.ZodObject<{
@@ -282,6 +291,7 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
                 healthy: "healthy";
                 never: "never";
             }>>;
+            runtimeReadyPath: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         debug: z.ZodOptional<z.ZodObject<{
             studio: z.ZodOptional<z.ZodBoolean>;
@@ -289,6 +299,13 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
         }, z.core.$strip>>;
         proxy: z.ZodOptional<z.ZodObject<{
             expose: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            routes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                segment: z.ZodString;
+                service: z.ZodString;
+                port: z.ZodOptional<z.ZodNumber>;
+                websocket: z.ZodOptional<z.ZodBoolean>;
+                auth: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>>;
         }, z.core.$strip>>;
         requiresWorkingDirectory: z.ZodOptional<z.ZodBoolean>;
         sideload: z.ZodOptional<z.ZodObject<{

package/index.js

@@ -34,6 +34,9 @@ const ProductTemplateUiSchema = z.object({
     runtimeScreenReadyWhen: z.enum(["running", "healthy", "never"]).optional().meta({
         description: "When the runner may offer the runtime-screen link, judged on `runtimeScreenService`'s own container state. Omit for the default `running` — the link goes live as soon as the service is up, which is the only state a service without a healthcheck ever reaches. `healthy` holds it back until the service's healthcheck passes, for a product whose screen 404s or misbehaves before it is fully warm. `never` suppresses the link entirely.",
     }),
+    runtimeReadyPath: z.string().startsWith("/").optional().meta({
+        description: "HTTP path on `runtimeScreenService` that answers 2xx only once the product's workflow is actually running — for a Studio-hosted product, `/live/api/components`, which 503s until the runner is up. Container health cannot tell: Studio's web server stays healthy after its runner has exited, so a workflow refused at start reads as `healthy` without this. The runner polls the path into the instance's `workflow` facet (`starting` | `running` | `refused`). Omit and the facet is absent — never guessed.",
+    }),
 });
 // Per-instance Debug menu toggles. The runner always offers raw Studio +
 // Visualiser debug surfaces for an instance; a product opts a link out when
@@ -47,10 +50,48 @@ const ProductTemplateDebugSchema = z.object({
         .optional()
         .meta({ description: "Show the Debug menu's 'Open Visualiser' link. Default true." }),
 });
+// Path segments the runner owns under /instance/<id>/ and a product may never
+// claim. They are the six base routes instance-routes.ts always emits; a
+// declared route colliding with one would be shadowed by nginx's more-specific
+// match and silently never serve, so the schema rejects it instead.
+export const RESERVED_INSTANCE_ROUTE_SEGMENTS = ["studio", "media", "visualiser", "uvis", "status", "metrics"];
+// One additional HTTP service a product wants behind the runner's front door,
+// beside the runtime-screen catch-all. WHY THIS EXISTS: a product's second UI
+// otherwise needs a published host port, and a plain http host port is a secure
+// context on localhost only — browser APIs like WebCodecs fail from any other
+// machine. The catch-all is a single slot, so a product with two UIs used to
+// have to reverse-proxy one behind the other itself, websocket bridging
+// included.
+const ProductTemplateRouteSchema = z.object({
+    segment: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9-]*$/, "one lowercase path segment: letters, digits and dashes")
+        .refine((s) => !RESERVED_INSTANCE_ROUTE_SEGMENTS.includes(s), {
+        message: `segment is reserved by the runner (${RESERVED_INSTANCE_ROUTE_SEGMENTS.join(", ")})`,
+    })
+        .meta({
+        description: "Single path segment under the instance root. The runner serves it at /instance/<id>/<segment>/. Must not be one of the runner's reserved segments (studio, media, visualiser, uvis, status, metrics).",
+    }),
+    service: z.string().min(1).meta({
+        description: "Compose service that serves this route. Must be a service in the template's own compose.yml; the runner dials it by its compose container name.",
+    }),
+    port: z.number().int().positive().optional().meta({
+        description: "Container port to dial. Omit for the conventional 8000.",
+    }),
+    websocket: z.boolean().optional().meta({
+        description: "Emit the Upgrade/Connection proxy headers so this route can carry websockets. Omit for a plain HTTP route. HTTP is always served; this only adds the upgrade path, so a route carrying both needs just this flag.",
+    }),
+    auth: z.boolean().optional().meta({
+        description: "Whether the route sits behind the runner's oauth2 auth_request. Omit for the default `true`. Set false only for a surface that must be reachable unauthenticated, as the media route is.",
+    }),
+});
 const ProductTemplateProxySchema = z.object({
     expose: z.array(z.string()).default([]).meta({
         description: "Paths (or globs) the runner's nginx routes through to this instance. Anything not in the list returns 404 from the proxy. Glob-shaped strings (`/static/*`) are accepted as hints — current implementation treats the whole set as a signal to mount a catch-all on the instance root; per-path filtering can come later.",
     }),
+    routes: z.array(ProductTemplateRouteSchema).optional().meta({
+        description: "Extra named services to route under the instance root, beside the runtime-screen catch-all. Additive and optional: a template that omits it routes exactly as before, so an older runner ignoring the field still launches the product.",
+    }),
 });
 // product-template-schema cannot import @norsk-ctl/shared (dependency direction), so
 // this is a literal copy of the runner's network-mode enum — and the runner

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-product-template-schema",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "type": "module",
   "exports": {
     ".": {