@ninedeploy/schemas 0.16.0 → 0.16.2

package/src/service.ts

@@ -4,6 +4,221 @@ import { containerPath, dockerVolumeName, envVarName, gitBranch, gitRepoUrl, htt
 export const serviceType = z.enum(['pm2', 'docker', 'compose']);
 export const buildPack = z.enum(['auto', 'nixpacks', 'dockerfile', 'railpack', 'static']);
 
+/**
+ * 0.16.1: names of the service's environment variables a Dockerfile build
+ * receives as `--build-arg` (the Dockerfile reads them with `ARG`). Opt-in per
+ * name: a build gets none unless listed. Nixpacks and Railpack builds already
+ * see the whole environment.
+ */
+export const buildArgNames = z.array(envVarName.max(100)).max(100);
+
+/**
+ * 0.16.2: the stage of a multi-stage Dockerfile to build (`docker build
+ * --target`), e.g. `runtime` or `prod`. Docker's own stage-name rule: a letter
+ * first, then letters, digits, `_`, `.` or `-` (so it can never read as a flag).
+ */
+export const dockerBuildTarget = z
+  .string()
+  .regex(/^[A-Za-z][A-Za-z0-9_.-]{0,127}$/, 'A stage name starts with a letter and holds letters, digits, _ . or -');
+
+/**
+ * 0.16.1: capabilities a docker service may add. Deliberately short: the ones
+ * real workloads ask for (VPNs, packet capture, profilers, realtime audio,
+ * mlock). SYS_ADMIN, SYS_MODULE, DAC_READ_SEARCH and the like are left out —
+ * each is a known path out of the container.
+ */
+export const runtimeCapability = z.enum(['NET_ADMIN', 'NET_RAW', 'SYS_PTRACE', 'SYS_NICE', 'SYS_RESOURCE', 'IPC_LOCK', 'SYS_TIME']);
+
+/**
+ * 0.16.1 advanced container options for docker services (operator only):
+ * structured fields, never free-form `docker run` flags, so nothing outside
+ * this list (privileged, host mounts, host network…) can be asked for.
+ */
+export const runtimeOptions = z
+  .object({
+    /** `--gpus all` or `--gpus <n>` (needs the NVIDIA container toolkit on the host). */
+    gpus: z.union([z.literal('all'), z.number().int().min(1).max(16)]).nullable().optional(),
+    /** `--shm-size` in MiB; browsers and PyTorch data loaders outgrow Docker's 64. */
+    shmSizeMb: z.number().int().min(1).max(65_536).nullable().optional(),
+    /** `--init`: reaps zombie processes and forwards signals to the app. */
+    init: z.boolean().optional(),
+    /** `--ulimit nofile=N:N`. */
+    ulimitNofile: z.number().int().min(1024).max(1_048_576).nullable().optional(),
+    /** `--cap-add`. */
+    capAdd: z.array(runtimeCapability).max(7).optional(),
+  })
+  .strict();
+export type RuntimeOptions = z.infer<typeof runtimeOptions>;
+
+/**
+ * 0.16.1: the most host ports one service may publish through `portMappings`.
+ * Docker starts one userland proxy process per published port and protocol,
+ * so a 10 000-port range costs 10 000 processes on the host.
+ */
+export const MAX_MAPPED_PORTS = 1000;
+/** Most port-mapping rules per service. */
+export const MAX_PORT_MAPPINGS = 20;
+
+const IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+
+/**
+ * A literal IPv4 or IPv6 address a port can be bound to (no zone, no CIDR).
+ * The unspecified addresses are refused: an empty IP already means "every
+ * address", and two spellings of it would dodge the overlap check.
+ */
+export function isBindableIp(ip: string): boolean {
+  if (IPV4.test(ip)) return ip !== '0.0.0.0';
+  if (ip.length > 45) return false;
+  const halves = ip.split('::');
+  if (halves.length > 2) return false;
+  const groups = halves.flatMap((h) => (h === '' ? [] : h.split(':')));
+  let width = groups.length;
+  if (groups.length > 0 && IPV4.test(groups[groups.length - 1]!)) {
+    groups.pop();
+    width += 1; // an embedded IPv4 fills two groups
+  }
+  if (!groups.every((g) => /^[0-9A-Fa-f]{1,4}$/.test(g))) return false;
+  if (halves.length === 2 ? width > 7 : width !== 8) return false;
+  // `::`, `0::0`, `0:0:0:0:0:0:0:0`: the unspecified address.
+  return width !== groups.length || groups.some((g) => Number.parseInt(g, 16) !== 0);
+}
+
+/**
+ * 0.16.1 extra host-port mappings of a docker service: one port or a range,
+ * TCP or UDP, on every host address or one dedicated IP
+ * (`docker run -p 203.0.113.7:27015-27030:27015-27030/udp`). The container
+ * range starts at `containerPort` and is as long as the host range.
+ */
+export const portMapping = z
+  .object({
+    /** Host address to bind; null or omitted = every address of the host. */
+    hostIp: z
+      .string()
+      .max(45)
+      .refine(isBindableIp, 'hostIp must be one IPv4 or IPv6 address of the host (leave it empty for every address)')
+      .nullable()
+      .optional(),
+    hostPort: z.number().int().min(1).max(65535),
+    /** Last host port of a range; null or omitted = the single `hostPort`. */
+    hostPortEnd: z.number().int().min(1).max(65535).nullable().optional(),
+    containerPort: z.number().int().min(1).max(65535),
+    protocol: z.enum(['tcp', 'udp']).default('tcp'),
+    /**
+     * TCP, one port: only these addresses or CIDR ranges may connect. The port
+     * is then published by a small Traefik proxy in front of the service
+     * instead of Docker's `-p`, which a host firewall cannot restrict.
+     */
+    allowFrom: z.array(z.string().trim().min(1).max(64)).min(1).max(100).nullable().optional(),
+  })
+  .strict();
+export type PortMapping = z.infer<typeof portMapping>;
+type PortMappingLike = Pick<PortMapping, 'hostPort' | 'hostPortEnd' | 'containerPort'> & {
+  hostIp?: string | null;
+  protocol?: 'tcp' | 'udp';
+  allowFrom?: readonly string[] | null;
+};
+
+/** How many host ports a mapping publishes. */
+export const mappedPortCount = (m: Pick<PortMapping, 'hostPort' | 'hostPortEnd'>): number =>
+  Math.max(1, (m.hostPortEnd ?? m.hostPort) - m.hostPort + 1);
+
+/**
+ * Whether two mappings would bind the same host socket: same protocol,
+ * overlapping ports, and the same IP (or either on every address).
+ */
+export function portMappingsOverlap(a: PortMappingLike, b: PortMappingLike): boolean {
+  if ((a.protocol ?? 'tcp') !== (b.protocol ?? 'tcp')) return false;
+  if (a.hostIp && b.hostIp && a.hostIp.toLowerCase() !== b.hostIp.toLowerCase()) return false;
+  return a.hostPort <= (b.hostPortEnd ?? b.hostPort) && b.hostPort <= (a.hostPortEnd ?? a.hostPort);
+}
+
+/** Why a list of mappings cannot be published, or null. Shared by the server, the panel and the CLI. */
+export function portMappingsProblem(list: readonly PortMappingLike[]): string | null {
+  let total = 0;
+  for (const [i, m] of list.entries()) {
+    const end = m.hostPortEnd ?? m.hostPort;
+    const label = formatPortMapping(m);
+    if (end < m.hostPort) return `Mapping ${i + 1} (${label}): the range ends before it starts.`;
+    if (m.containerPort + (end - m.hostPort) > 65535) return `Mapping ${i + 1} (${label}): the container range runs past 65535.`;
+    total += end - m.hostPort + 1;
+    if (m.allowFrom?.length && ((m.protocol ?? 'tcp') !== 'tcp' || end !== m.hostPort)) {
+      return `Mapping ${i + 1} (${label}): an allow list works on one TCP port (UDP and ranges cannot be filtered by source).`;
+    }
+    const other = list.slice(0, i).find((o) => portMappingsOverlap(o, m));
+    if (other) {
+      return `Mapping ${i + 1} (${label}) overlaps ${formatPortMapping(other)}: a host port can be published once per address and protocol.`;
+    }
+  }
+  if (total > MAX_MAPPED_PORTS) {
+    return `${total} host ports requested; at most ${MAX_MAPPED_PORTS} per service (Docker runs one proxy process per published port).`;
+  }
+  return null;
+}
+
+/** The `docker run -p` operand: `27015-27030:27015-27030/udp`, `203.0.113.7:53:53/udp`, `[2001:db8::7]:53:53/udp`. */
+export function formatPortMapping(m: PortMappingLike): string {
+  const span = (m.hostPortEnd ?? m.hostPort) - m.hostPort;
+  const range = (start: number) => (span > 0 ? `${start}-${start + span}` : String(start));
+  const ip = m.hostIp ? (m.hostIp.includes(':') ? `[${m.hostIp}]:` : `${m.hostIp}:`) : '';
+  return `${ip}${range(m.hostPort)}:${range(m.containerPort)}/${m.protocol ?? 'tcp'}`;
+}
+
+/**
+ * Parse `27015-27030:27015/udp`, `8080:80`, `5432@10.0.0.0/8`, `53/udp`, `10000-10100/udp`
+ * (no colon = the same ports inside the container), optionally after an IP:
+ * `203.0.113.7:53/udp`, `[2001:db8::7]:8080:80`. A container range must be as
+ * long as the host range. Returns the mapping, or why the text is not one.
+ */
+export function parsePortMapping(text: string): PortMapping | string {
+  // `…@10.0.0.0/8,203.0.113.4`: the allow list of a TCP port.
+  const parts = text.trim().split('@');
+  const t = parts[0]!;
+  const allowText = parts[1];
+  if (parts.length > 2) return `"${text.trim()}" has more than one @.`;
+  const allowFrom = allowText === undefined ? null : allowText.split(',').map((e) => e.trim()).filter(Boolean);
+  if (allowFrom && allowFrom.length === 0) return `"${text.trim()}": list the addresses after @ (10.0.0.0/8,203.0.113.4).`;
+  const m = /^(?:(\d{1,3}(?:\.\d{1,3}){3})|\[([0-9A-Fa-f:.]+)\]):(\d{1,5})(?:-(\d{1,5}))?(?::(\d{1,5})(?:-(\d{1,5}))?)?(?:\/(tcp|udp))?$/i.exec(t)
+    ?? /^()()(\d{1,5})(?:-(\d{1,5}))?(?::(\d{1,5})(?:-(\d{1,5}))?)?(?:\/(tcp|udp))?$/i.exec(t);
+  if (!m) return `"${t}" is not a port mapping (examples: 8080:80, 27015-27030:27015/udp, 203.0.113.7:53/udp).`;
+  const hostIp = m[1] || m[2] || null;
+  if (hostIp && !isBindableIp(hostIp)) return `"${t}": ${hostIp} is not an address a port can be bound to.`;
+  const hostPort = Number(m[3]);
+  const hostPortEnd = m[4] ? Number(m[4]) : null;
+  const containerPort = m[5] ? Number(m[5]) : hostPort;
+  const ports = [hostPort, hostPortEnd ?? hostPort, containerPort];
+  if (ports.some((p) => p < 1 || p > 65535)) return `"${t}": ports run from 1 to 65535.`;
+  if (hostPortEnd !== null && hostPortEnd < hostPort) return `"${t}": the range ends before it starts.`;
+  if (m[6] && Number(m[6]) - containerPort !== (hostPortEnd ?? hostPort) - hostPort) {
+    return `"${t}": the container range must be as long as the host range.`;
+  }
+  return {
+    hostIp,
+    hostPort,
+    hostPortEnd: hostPortEnd !== null && hostPortEnd !== hostPort ? hostPortEnd : null,
+    containerPort,
+    protocol: (m[7]?.toLowerCase() ?? 'tcp') as 'tcp' | 'udp',
+    ...(allowFrom ? { allowFrom } : {}),
+  };
+}
+
+/** The PATCH field: rules checked together (ranges, overlaps, the port budget). */
+export const portMappings = z
+  .array(portMapping)
+  .max(MAX_PORT_MAPPINGS)
+  .superRefine((list, ctx) => {
+    const problem = portMappingsProblem(list);
+    if (problem) ctx.addIssue({ code: 'custom', message: problem });
+  });
+
+/**
+ * 0.16.1 deploy healthcheck: `http` probes the container port (an HTTP answer
+ * below 500, then a TCP connect); `running` only waits for the container to
+ * stay up, for services with no HTTP or TCP port to probe (UDP game servers,
+ * VoIP, queue workers).
+ */
+export const healthCheckMode = z.enum(['http', 'running']);
+export type HealthCheckMode = z.infer<typeof healthCheckMode>;
+
 /** Optional project/workspace/label tag IDs for new service creation. */
 const tagIds = z.array(z.number().int().positive()).optional();
 
@@ -74,6 +289,10 @@ export const createService = z.object({
       restartPolicy: z.string().regex(/^(no|always|unless-stopped|on-failure(?::\d{1,3})?)$/).optional(),
       // Seconds between SIGTERM and SIGKILL on stop (docker stop -t).
       stopGraceSeconds: z.number().int().min(0).max(300).optional(),
+      /** Env-var names passed to a Dockerfile build as `--build-arg`. */
+      buildArgs: buildArgNames.optional(),
+      /** Stage of a multi-stage Dockerfile to build (`--target`); absent = the last stage. */
+      buildTarget: dockerBuildTarget.optional(),
     })
     .default({ buildPack: 'auto', baseDir: '/' }),
 }).superRefine((value, ctx) => {
@@ -134,8 +353,16 @@ export const updateService = z.object({
   /** Horizontal replica count for docker services (Traefik load-balances). */
   replicas: z.number().int().min(1).max(10).optional(),
   healthPath: httpPath.optional(),
+  /** Seconds a deploy waits for the healthcheck (10–3600); null restores the 300 s default. */
+  healthTimeoutSeconds: z.number().int().min(10).max(3600).nullable().optional(),
+  /** 'running' = the deploy only waits for the container to stay up (UDP and other non-HTTP services); 'http' or null = the HTTP/TCP probe. */
+  healthCheck: healthCheckMode.nullable().optional(),
+  /** Operator only: advanced container options; null clears them all. */
+  runtimeOptions: runtimeOptions.nullable().optional(),
   port: z.number().int().min(1).max(65535).optional(),
   publishedPort: z.number().int().min(1).max(65535).nullable().optional(),
+  /** Extra host ports, TCP or UDP, single or ranges (docker services on the panel host); null or [] clears them. */
+  portMappings: portMappings.nullable().optional(),
   previewDeploymentsEnabled: z.boolean().optional(),
   previewAutoDestroyOnClose: z.boolean().optional(),
   previewDomainPattern: z.string().nullable().optional(),
@@ -159,6 +386,10 @@ export const updateService = z.object({
       preStopCmd: z.string().nullable().optional(),
       restartPolicy: z.string().regex(/^(no|always|unless-stopped|on-failure(?::\d{1,3})?)$/).optional(),
       stopGraceSeconds: z.number().int().min(0).max(300).optional(),
+      /** Env-var names passed to a Dockerfile build as `--build-arg`; [] clears. */
+      buildArgs: buildArgNames.optional(),
+      /** Stage of a multi-stage Dockerfile to build (`--target`); '' or null clears. */
+      buildTarget: z.union([dockerBuildTarget, z.literal('')]).nullable().optional(),
     })
     .optional(),
 });
@@ -209,9 +440,17 @@ export const service = z.object({
   commitSha: z.string().nullable(),
   runtimeId: z.string().nullable(),
   healthPath: z.string(),
+  /** Healthcheck deadline in seconds; null = the 300 s default (0.16.1). */
+  healthTimeoutSeconds: z.number().int().nullable().optional(),
+  /** How a deploy decides the new container is ready (0.16.1). */
+  healthCheck: healthCheckMode.optional(),
+  /** Advanced container options (0.16.1); null = none. */
+  runtimeOptions: runtimeOptions.nullable().optional(),
   autoUrl: z.string().nullable(),
   port: z.number().int().nullable(),
   publishedPort: z.number().int().nullable().optional(),
+  /** Extra host-port mappings, TCP or UDP (0.16.1); [] = none. */
+  portMappings: z.array(portMapping).optional(),
   cpuShares: z.number().int(),
   cpuLimitMilli: z.number().int(),
   memLimitMb: z.number().int(),
@@ -242,6 +481,10 @@ export const service = z.object({
       preStopCmd: z.string().nullable().optional(),
       restartPolicy: z.string(),
       stopGraceSeconds: z.number().int(),
+      /** Env-var names a Dockerfile build receives as `--build-arg` (0.16.1). */
+      buildArgs: z.array(z.string()).optional(),
+      /** Stage of a multi-stage Dockerfile the build stops at; null = the last (0.16.2). */
+      buildTarget: z.string().nullable().optional(),
     })
     .nullable(),
   createdAt: z.string().datetime(),
@@ -381,6 +624,40 @@ export const createDomain = z.object({
 });
 export type CreateDomainInput = z.input<typeof createDomain>;
 
+/**
+ * Why a redirect regex cannot go to Traefik, or null. Traefik compiles it
+ * with Go's RE2, which has no lookaround and no backreferences — and a regex
+ * Traefik refuses takes the whole dynamic config file down with it, so these
+ * are refused when saved. The rest is checked by compiling it here.
+ */
+export function redirectRegexProblem(regex: string): string | null {
+  if (/\(\?<?[=!]/.test(regex)) return 'lookahead / lookbehind are not supported (Traefik uses Go RE2)';
+  if (/\\[1-9]/.test(regex)) return 'backreferences such as \\1 are not supported (Traefik uses Go RE2)';
+  try {
+    new RegExp(regex);
+  } catch (err) {
+    // RegExp only ever throws a SyntaxError here.
+    return `not a valid regular expression (${(err as Error).message})`;
+  }
+  return null;
+}
+
+/** 0.16.1 one redirect rule of a domain (Dokploy's "Redirects"): Traefik `redirectRegex`. */
+export const redirectRule = z
+  .object({
+    /** Matched against the full request URL, e.g. `^https://example.com/old/(.*)`. */
+    regex: z.string().min(1).max(1000),
+    /** The target; `${1}` inserts the first capture group. */
+    replacement: z.string().min(1).max(2000).regex(/^[^\r\n]*$/, 'one line'),
+    /** 301/308 when true, 302/307 when false. */
+    permanent: z.boolean().default(false),
+  })
+  .superRefine((r, ctx) => {
+    const problem = redirectRegexProblem(r.regex);
+    if (problem) ctx.addIssue({ code: 'custom', path: ['regex'], message: problem });
+  });
+export type RedirectRule = z.infer<typeof redirectRule>;
+
 /** PATCHable routing extras for an existing domain. */
 export const domainPatch = z.object({
   ssl: z.boolean().optional(),
@@ -390,6 +667,8 @@ export const domainPatch = z.object({
   ipAllowlist: z.string().max(4000).optional().nullable(),
   rateLimitAverage: z.number().int().min(0).max(100000).optional().nullable(),
   rateLimitBurst: z.number().int().min(0).max(100000).optional().nullable(),
+  /** 0.16.1: redirect rules, applied in order; null or [] removes them. */
+  redirects: z.array(redirectRule).max(10).optional().nullable(),
 });
 export type DomainPatch = z.input<typeof domainPatch>;
 
@@ -405,6 +684,8 @@ export const domain = z.object({
   ipAllowlist: z.string().nullable().optional(),
   rateLimitAverage: z.number().nullable().optional(),
   rateLimitBurst: z.number().nullable().optional(),
+  /** 0.16.1 redirect rules (absent on older panels). */
+  redirects: z.array(z.object({ regex: z.string(), replacement: z.string(), permanent: z.boolean() })).optional(),
   status: z.string(),
   createdAt: z.string().datetime(),
   updatedAt: z.string().datetime(),