@serve.zone/interfaces 7.28.0 → 8.0.0

package/changelog.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2026-07-04 - 8.0.0
+
+### Breaking Changes
+
+- introduce canonical service port routing contracts (service-ports)
+  - Add shared service target port, domain route, public port mapping, and normalization helper contracts.
+  - Update service and App Store interfaces to support targetPorts, domain target references, and publicPortMappings.
+  - Extend gateway and Coretraffic routing contracts with transport-aware port routes, routeRef ownership, and remoteIngress intent.
+  - Breaking change: legacy SSH domain routing is no longer represented through domain protocol values; public TCP/UDP exposure now uses publicPortMappings.
+
 ## 2026-06-24 - 7.28.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '7.28.0',
+    version: '8.0.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/appstore/types.d.ts

@@ -1,3 +1,4 @@
+import type { IServiceDomainRoute, IServicePublicPortMapping, IServiceTargetPort } from '../data/serviceports.js';
 export type TAppStorePlatformRequirement = 'mongodb' | 's3' | 'clickhouse' | 'valkey' | 'mariadb';
 export type TAppStoreSourceType = 'inline' | 'repoManifest' | 'dockerImage';
 export type TAppStoreTrackingMode = 'tag' | 'digest';
@@ -98,7 +99,12 @@ export interface IAppStoreAppMeta {
 }
 export interface IAppStoreVersionConfig {
     image: string;
-    port: number;
+    /** Legacy shorthand for targetPorts.web. New templates should prefer targetPorts. */
+    port?: number;
+    targetPorts?: IServiceTargetPort[];
+    domains?: IServiceDomainRoute[];
+    /** Edge/coretraffic public TCP/UDP exposure, distinct from Docker publishedPorts. */
+    publicPortMappings?: IServicePublicPortMapping[];
     envVars?: IAppStoreEnvVar[];
     volumes?: TAppStoreVolumeSpec[];
     publishedPorts?: IAppStorePublishedPort[];
@@ -155,8 +161,10 @@ export interface IAppStoreInstallRequest {
     version?: string;
     serviceName: string;
     domain?: string;
+    /** Legacy install-time override for the web target port. */
     port?: number;
     publishedPorts?: IAppStorePublishedPort[];
+    publicPortMappings?: IServicePublicPortMapping[];
     envVars?: Record<string, string>;
 }
 export interface IUpgradeableAppStoreService {

package/dist_ts/data/gateway.d.ts

@@ -173,7 +173,10 @@ export interface IGatewayClientOwnership {
     gatewayClientId?: string;
     /** App identifier within the owning gateway client platform. */
     appId: string;
-    hostname: string;
+    /** Hostname ownership for domain routes. Preserved for existing route keys. */
+    hostname?: string;
+    /** Stable non-domain route key, for example public-port mapping exposure refs. */
+    routeRef?: string;
 }
 /**
  * A single forward target of a gateway route.
@@ -187,7 +190,8 @@ export interface IGatewayRouteTarget {
  */
 export interface IGatewayRouteMatch {
     ports: number[];
-    domains: string[];
+    domains?: string[];
+    transport?: 'tcp' | 'udp' | 'all';
     path?: string;
 }
 /**
@@ -220,6 +224,10 @@ export interface IGatewayRouteConfig {
     name: string;
     match: IGatewayRouteMatch;
     action: IGatewayRouteAction;
+    remoteIngress?: {
+        enabled: boolean;
+        edgeFilter?: string[];
+    };
 }
 /**
  * Result of an idempotent gateway route sync.

package/dist_ts/data/index.d.ts

@@ -21,6 +21,7 @@ export * from './backup.js';
 export * from './clusternode.js';
 export * from './settings.js';
 export * from './service.js';
+export * from './serviceports.js';
 export * from './status.js';
 export * from './taskexecution.js';
 export * from './traffic.js';

package/dist_ts/data/index.js

@@ -21,9 +21,10 @@ export * from './backup.js';
 export * from './clusternode.js';
 export * from './settings.js';
 export * from './service.js';
+export * from './serviceports.js';
 export * from './status.js';
 export * from './taskexecution.js';
 export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxjQUFjLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGNBQWMsQ0FBQyJ9

package/dist_ts/data/service.d.ts

@@ -3,6 +3,7 @@ import type { IRegistryTarget } from './registry.js';
 import type { IAppStorePublishedPort } from '../appstore/index.js';
 import type { IHostedAppLifecycleState } from './hostedapp.js';
 import type { IServiceMailConfig } from './mail.js';
+import type { IServiceDomainRoute, IServicePublicPortMapping, IServiceTargetPort } from './serviceports.js';
 export interface IServiceVolume {
     /** Stable Docker volume name. If omitted, Coreflow derives one from service id and mount path. */
     name?: string;
@@ -109,8 +110,21 @@ export interface IService {
         antiAffinity?: boolean;
         scaleFactor: number;
         balancingStrategy: 'round-robin' | 'least-connections';
+        /**
+         * Canonical backend/container ports for this service. New domain routes
+         * and public mappings reference these targets by name or exact port.
+         */
+        targetPorts?: IServiceTargetPort[];
         ports: {
+            /**
+             * Legacy main backend port. New writes should declare targetPorts and
+             * keep this only as compatibility shorthand during migration.
+             */
             web: number;
+            /**
+             * Legacy implicit domain-to-port routes. Runtime code must not treat
+             * this as a permissive routing source for new services.
+             */
             custom?: {
                 [domain: string]: string;
             };
@@ -118,31 +132,10 @@ export interface IService {
         mail?: IServiceMailConfig;
         volumes?: IServiceVolume[];
         publishedPorts?: IAppStorePublishedPort[];
+        /** Edge/coretraffic public TCP/UDP exposure, distinct from Docker Swarm publishedPorts. */
+        publicPortMappings?: IServicePublicPortMapping[];
         resources?: IServiceRessources;
-        domains: {
-            /**
-             * Optional domain ID to specify which domain to use
-             * If not specified, will use the default domain or require manual configuration
-             */
-            domainId?: string;
-            /**
-             * The subdomain name (e.g., 'api', 'www', '@' for root)
-             */
-            name: string;
-            /**
-             * The port to expose (defaults to ports.web if not specified)
-             */
-            port?: number;
-            /**
-             * The protocol for this domain entry
-             */
-            protocol?: 'http' | 'https' | 'ssh';
-            /**
-             * Gateway source profile for this domain's route (e.g. 'standard'
-             * for internal-only access). Defaults to the gateway's public profile.
-             */
-            sourceProfileRef?: string;
-        }[];
+        domains: IServiceDomainRoute[];
         deploymentIds: string[];
     };
 }

package/dist_ts/data/serviceports.d.ts

@@ -0,0 +1,76 @@
+export type TServiceTargetProtocol = 'http' | 'https' | 'ssh' | 'tcp' | 'udp' | `custom:${string}`;
+export type TServiceTargetPortRef = string | number;
+export interface IServiceTargetPort {
+    name: string;
+    port: number;
+    portEnd?: number;
+    protocol: TServiceTargetProtocol;
+    description?: string;
+    default?: boolean;
+}
+export interface IServiceDomainRoute {
+    domainId?: string;
+    name: string;
+    targetPort?: TServiceTargetPortRef;
+    /**
+     * Legacy backend target port. New writes must use targetPort.
+     */
+    port?: number;
+    protocol?: 'http' | 'https';
+    sourceProfileRef?: string;
+}
+export interface IServicePublicPortMapping {
+    name: string;
+    publicPort: number;
+    publicPortEnd?: number;
+    targetPort: TServiceTargetPortRef;
+    protocol: 'tcp' | 'udp';
+    sourceProfileRef?: string;
+    exclusive: true;
+}
+export interface IResolvedServiceDomainRoute extends IServiceDomainRoute {
+    targetPort: TServiceTargetPortRef;
+    target: IServiceTargetPort;
+}
+export interface IResolvedServicePublicPortMapping extends IServicePublicPortMapping {
+    target: IServiceTargetPort;
+    targetPortStart: number;
+    targetPortEnd: number;
+    publicPortEnd: number;
+}
+export interface IServicePortSourceData {
+    name?: string;
+    ports?: {
+        web?: number;
+        custom?: Record<string, string>;
+    };
+    targetPorts?: IServiceTargetPort[];
+    domains?: IServiceDomainRoute[];
+    publicPortMappings?: IServicePublicPortMapping[];
+}
+export interface INormalizedServicePortConfig {
+    targetPorts: IServiceTargetPort[];
+    defaultTargetPort?: IServiceTargetPort;
+    domains: IResolvedServiceDomainRoute[];
+    publicPortMappings: IResolvedServicePublicPortMapping[];
+}
+export interface IServicePortNormalizationOptions {
+    /**
+     * Accept legacy domains[].port only when it resolves to a declared target.
+     * Defaults to true for staged migration reads.
+     */
+    allowLegacyDomainPort?: boolean;
+    /**
+     * Domain routes are HTTP(S) virtual-host routes. Defaults to true.
+     */
+    requireHttpDomainTargets?: boolean;
+}
+export declare function normalizeServicePortConfig(serviceDataArg: IServicePortSourceData, optionsArg?: IServicePortNormalizationOptions): INormalizedServicePortConfig;
+export declare function normalizeServicePortData<T extends IServicePortSourceData>(serviceDataArg: T, optionsArg?: IServicePortNormalizationOptions): T & {
+    targetPorts: IServiceTargetPort[];
+    domains?: IServiceDomainRoute[];
+    publicPortMappings?: IServicePublicPortMapping[];
+};
+export declare function resolveServiceTargetPort(targetPortsArg: IServiceTargetPort[], refArg: TServiceTargetPortRef): IServiceTargetPort | undefined;
+export declare function resolveDefaultServiceTargetPort(targetPortsArg: IServiceTargetPort[]): IServiceTargetPort | undefined;
+export declare function isHttpServiceTargetProtocol(protocolArg: TServiceTargetProtocol): boolean;

package/dist_ts/data/serviceports.js

@@ -0,0 +1,210 @@
+export function normalizeServicePortConfig(serviceDataArg, optionsArg = {}) {
+    const options = {
+        allowLegacyDomainPort: optionsArg.allowLegacyDomainPort ?? true,
+        requireHttpDomainTargets: optionsArg.requireHttpDomainTargets ?? true,
+    };
+    const serviceName = serviceDataArg.name || 'service';
+    const targetPorts = normalizeServiceTargetPorts(serviceDataArg, serviceName);
+    const defaultTargetPort = resolveDefaultServiceTargetPort(targetPorts);
+    const domains = (serviceDataArg.domains || []).map((domainArg) => {
+        const target = resolveServiceDomainTarget(domainArg, targetPorts, defaultTargetPort, serviceName, options);
+        if (options.requireHttpDomainTargets && !isHttpServiceTargetProtocol(target.protocol)) {
+            throw new Error(`Domain ${domainArg.name} on ${serviceName} references non-HTTP target '${target.name}' (${target.protocol})`);
+        }
+        if (target.portEnd && target.portEnd !== target.port) {
+            throw new Error(`Domain ${domainArg.name} on ${serviceName} references ranged target '${target.name}'`);
+        }
+        const normalizedDomain = {
+            ...domainArg,
+            targetPort: domainArg.targetPort ?? target.name,
+            target,
+        };
+        delete normalizedDomain.port;
+        return normalizedDomain;
+    });
+    const publicPortMappings = normalizeServicePublicPortMappings(serviceDataArg.publicPortMappings || [], targetPorts, serviceName);
+    return {
+        targetPorts,
+        defaultTargetPort,
+        domains,
+        publicPortMappings,
+    };
+}
+export function normalizeServicePortData(serviceDataArg, optionsArg = {}) {
+    const normalized = normalizeServicePortConfig(serviceDataArg, optionsArg);
+    return {
+        ...serviceDataArg,
+        targetPorts: normalized.targetPorts,
+        domains: normalized.domains.map(({ target, ...domainArg }) => domainArg),
+        publicPortMappings: normalized.publicPortMappings.map(({ target, targetPortStart, targetPortEnd, ...mappingArg }) => mappingArg),
+    };
+}
+export function resolveServiceTargetPort(targetPortsArg, refArg) {
+    if (typeof refArg === 'string') {
+        const normalizedRef = refArg.trim().toLowerCase();
+        return targetPortsArg.find((targetArg) => targetArg.name.trim().toLowerCase() === normalizedRef);
+    }
+    return targetPortsArg.find((targetArg) => targetArg.port === refArg && !targetArg.portEnd);
+}
+export function resolveDefaultServiceTargetPort(targetPortsArg) {
+    const explicitDefaults = targetPortsArg.filter((targetArg) => targetArg.default);
+    if (explicitDefaults.length > 1) {
+        throw new Error(`Multiple default target ports declared: ${explicitDefaults.map((targetArg) => targetArg.name).join(', ')}`);
+    }
+    return explicitDefaults[0]
+        || targetPortsArg.find((targetArg) => targetArg.name === 'web')
+        || targetPortsArg.find((targetArg) => isHttpServiceTargetProtocol(targetArg.protocol))
+        || targetPortsArg[0];
+}
+export function isHttpServiceTargetProtocol(protocolArg) {
+    return protocolArg === 'http' || protocolArg === 'https';
+}
+function normalizeServiceTargetPorts(serviceDataArg, serviceNameArg) {
+    const declaredTargets = [...(serviceDataArg.targetPorts || [])];
+    const legacyWebPort = Number(serviceDataArg.ports?.web);
+    if (declaredTargets.length === 0 && Number.isInteger(legacyWebPort) && legacyWebPort > 0) {
+        declaredTargets.push({
+            name: 'web',
+            port: legacyWebPort,
+            protocol: 'http',
+            default: true,
+        });
+    }
+    if (declaredTargets.length === 0) {
+        return [];
+    }
+    const seenNames = new Set();
+    const seenTuples = new Set();
+    const normalizedTargets = declaredTargets.map((targetArg) => {
+        const name = targetArg.name?.trim();
+        if (!name || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,62}$/.test(name)) {
+            throw new Error(`Invalid target port name '${targetArg.name}' on ${serviceNameArg}`);
+        }
+        const normalizedName = name.toLowerCase();
+        if (seenNames.has(normalizedName)) {
+            throw new Error(`Duplicate target port name '${name}' on ${serviceNameArg}`);
+        }
+        seenNames.add(normalizedName);
+        const port = assertValidServicePort(targetArg.port, `target port ${name} on ${serviceNameArg}`);
+        const portEnd = targetArg.portEnd === undefined
+            ? undefined
+            : assertValidServicePort(targetArg.portEnd, `target port end ${name} on ${serviceNameArg}`);
+        if (portEnd !== undefined && portEnd < port) {
+            throw new Error(`target port range '${name}' on ${serviceNameArg} must be ascending`);
+        }
+        const protocol = targetArg.protocol || 'tcp';
+        const tuple = `${protocol}:${port}:${portEnd || port}`;
+        if (seenTuples.has(tuple)) {
+            throw new Error(`Duplicate target port tuple ${tuple} on ${serviceNameArg}`);
+        }
+        seenTuples.add(tuple);
+        return {
+            ...targetArg,
+            name,
+            port,
+            portEnd,
+            protocol,
+        };
+    });
+    if (!normalizedTargets.some((targetArg) => targetArg.default)) {
+        const webTarget = normalizedTargets.find((targetArg) => targetArg.name === 'web');
+        if (webTarget) {
+            webTarget.default = true;
+        }
+    }
+    return normalizedTargets;
+}
+function resolveServiceDomainTarget(domainArg, targetPortsArg, defaultTargetPortArg, serviceNameArg, optionsArg) {
+    const domainName = domainArg.name || '(unnamed domain)';
+    if (!targetPortsArg.length) {
+        throw new Error(`Domain ${domainName} on ${serviceNameArg} requires at least one declared target port`);
+    }
+    if (domainArg.targetPort !== undefined) {
+        const target = resolveServiceTargetPort(targetPortsArg, domainArg.targetPort);
+        if (!target) {
+            throw new Error(`Domain ${domainName} on ${serviceNameArg} references undeclared targetPort '${domainArg.targetPort}'`);
+        }
+        return target;
+    }
+    if (domainArg.port !== undefined) {
+        if (!optionsArg.allowLegacyDomainPort) {
+            throw new Error(`Domain ${domainName} on ${serviceNameArg} uses legacy port; use targetPort instead`);
+        }
+        const legacyPort = Number(domainArg.port);
+        const target = resolveServiceTargetPort(targetPortsArg, legacyPort);
+        if (!target) {
+            throw new Error(`Domain ${domainName} on ${serviceNameArg} references undeclared legacy port ${domainArg.port}`);
+        }
+        return target;
+    }
+    if (!defaultTargetPortArg) {
+        throw new Error(`Domain ${domainName} on ${serviceNameArg} has no targetPort and no default target port exists`);
+    }
+    return defaultTargetPortArg;
+}
+function normalizeServicePublicPortMappings(mappingsArg, targetPortsArg, serviceNameArg) {
+    const seenNames = new Set();
+    const seenPublicPorts = new Set();
+    return mappingsArg.map((mappingArg) => {
+        const name = mappingArg.name?.trim();
+        if (!name || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,62}$/.test(name)) {
+            throw new Error(`Invalid public port mapping name '${mappingArg.name}' on ${serviceNameArg}`);
+        }
+        const normalizedName = name.toLowerCase();
+        if (seenNames.has(normalizedName)) {
+            throw new Error(`Duplicate public port mapping '${name}' on ${serviceNameArg}`);
+        }
+        seenNames.add(normalizedName);
+        if (mappingArg.exclusive !== true) {
+            throw new Error(`Public port mapping '${name}' on ${serviceNameArg} must be exclusive`);
+        }
+        if (!['tcp', 'udp'].includes(mappingArg.protocol)) {
+            throw new Error(`Public port mapping '${name}' on ${serviceNameArg} has unsupported protocol '${mappingArg.protocol}'`);
+        }
+        const target = resolveServiceTargetPort(targetPortsArg, mappingArg.targetPort);
+        if (!target) {
+            throw new Error(`Public port mapping '${name}' on ${serviceNameArg} references undeclared targetPort '${mappingArg.targetPort}'`);
+        }
+        const publicPort = assertValidServicePort(mappingArg.publicPort, `public port ${name} on ${serviceNameArg}`);
+        const targetStart = target.port;
+        const targetEnd = target.portEnd || target.port;
+        const publicPortEnd = mappingArg.publicPortEnd === undefined
+            ? publicPort + (targetEnd - targetStart)
+            : assertValidServicePort(mappingArg.publicPortEnd, `public port end ${name} on ${serviceNameArg}`);
+        if (publicPortEnd < publicPort) {
+            throw new Error(`Public port mapping '${name}' on ${serviceNameArg} must have an ascending public range`);
+        }
+        if ((publicPortEnd - publicPort) !== (targetEnd - targetStart)) {
+            throw new Error(`Public and target port ranges must have the same length for mapping '${name}' on ${serviceNameArg}`);
+        }
+        for (let offset = 0; offset <= publicPortEnd - publicPort; offset++) {
+            const key = `${mappingArg.protocol}:${publicPort + offset}`;
+            if (seenPublicPorts.has(key)) {
+                throw new Error(`Duplicate public port ${publicPort + offset}/${mappingArg.protocol} on ${serviceNameArg}`);
+            }
+            seenPublicPorts.add(key);
+        }
+        return {
+            ...mappingArg,
+            name,
+            publicPort,
+            publicPortEnd,
+            protocol: mappingArg.protocol,
+            target,
+            targetPortStart: targetStart,
+            targetPortEnd: targetEnd,
+        };
+    }).sort((a, b) => {
+        return a.protocol.localeCompare(b.protocol)
+            || a.publicPort - b.publicPort
+            || a.name.localeCompare(b.name);
+    });
+}
+function assertValidServicePort(portArg, labelArg) {
+    const port = Number(portArg);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid ${labelArg}: ${portArg}. Expected an integer between 1 and 65535.`);
+    }
+    return port;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VydmljZXBvcnRzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9zZXJ2aWNlcG9ydHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBbUZBLE1BQU0sVUFBVSwwQkFBMEIsQ0FDeEMsY0FBc0MsRUFDdEMsYUFBK0MsRUFBRTtJQUVqRCxNQUFNLE9BQU8sR0FBK0M7UUFDMUQscUJBQXFCLEVBQUUsVUFBVSxDQUFDLHFCQUFxQixJQUFJLElBQUk7UUFDL0Qsd0JBQXdCLEVBQUUsVUFBVSxDQUFDLHdCQUF3QixJQUFJLElBQUk7S0FDdEUsQ0FBQztJQUNGLE1BQU0sV0FBVyxHQUFHLGNBQWMsQ0FBQyxJQUFJLElBQUksU0FBUyxDQUFDO0lBQ3JELE1BQU0sV0FBVyxHQUFHLDJCQUEyQixDQUFDLGNBQWMsRUFBRSxXQUFXLENBQUMsQ0FBQztJQUM3RSxNQUFNLGlCQUFpQixHQUFHLCtCQUErQixDQUFDLFdBQVcsQ0FBQyxDQUFDO0lBQ3ZFLE1BQU0sT0FBTyxHQUFHLENBQUMsY0FBYyxDQUFDLE9BQU8sSUFBSSxFQUFFLENBQUMsQ0FBQyxHQUFHLENBQUMsQ0FBQyxTQUFTLEVBQUUsRUFBRTtRQUMvRCxNQUFNLE1BQU0sR0FBRywwQkFBMEIsQ0FBQyxTQUFTLEVBQUUsV0FBVyxFQUFFLGlCQUFpQixFQUFFLFdBQVcsRUFBRSxPQUFPLENBQUMsQ0FBQztRQUMzRyxJQUFJLE9BQU8sQ0FBQyx3QkFBd0IsSUFBSSxDQUFDLDJCQUEyQixDQUFDLE1BQU0sQ0FBQyxRQUFRLENBQUMsRUFBRSxDQUFDO1lBQ3RGLE1BQU0sSUFBSSxLQUFLLENBQUMsVUFBVSxTQUFTLENBQUMsSUFBSSxPQUFPLFdBQVcsZ0NBQWdDLE1BQU0sQ0FBQyxJQUFJLE1BQU0sTUFBTSxDQUFDLFFBQVEsR0FBRyxDQUFDLENBQUM7UUFDakksQ0FBQztRQUNELElBQUksTUFBTSxDQUFDLE9BQU8sSUFBSSxNQUFNLENBQUMsT0FBTyxLQUFLLE1BQU0sQ0FBQyxJQUFJLEVBQUUsQ0FBQztZQUNyRCxNQUFNLElBQUksS0FBSyxDQUFDLFVBQVUsU0FBUyxDQUFDLElBQUksT0FBTyxXQUFXLDhCQUE4QixNQUFNLENBQUMsSUFBSSxHQUFHLENBQUMsQ0FBQztRQUMxRyxDQUFDO1FBQ0QsTUFBTSxnQkFBZ0IsR0FBZ0M7WUFDcEQsR0FBRyxTQUFTO1lBQ1osVUFBVSxFQUFFLFNBQVMsQ0FBQyxVQUFVLElBQUksTUFBTSxDQUFDLElBQUk7WUFDL0MsTUFBTTtTQUNQLENBQUM7UUFDRixPQUFPLGdCQUFnQixDQUFDLElBQUksQ0FBQztRQUM3QixPQUFPLGdCQUFnQixDQUFDO0lBQzFCLENBQUMsQ0FBQyxDQUFDO0lBQ0gsTUFBTSxrQkFBa0IsR0FBRyxrQ0FBa0MsQ0FDM0QsY0FBYyxDQUFDLGtCQUFrQixJQUFJLEVBQUUsRUFDdkMsV0FBVyxFQUNYLFdBQVcsQ0FDWixDQUFDO0lBQ0YsT0FBTztRQUNMLFdBQVc7UUFDWCxpQkFBaUI7UUFDakIsT0FBTztRQUNQLGtCQUFrQjtLQUNuQixDQUFDO0FBQ0osQ0FBQztBQUVELE1BQU0sVUFBVSx3QkFBd0IsQ0FDdEMsY0FBaUIsRUFDakIsYUFBK0MsRUFBRTtJQU1qRCxNQUFNLFVBQVUsR0FBRywwQkFBMEIsQ0FBQyxjQUFjLEVBQUUsVUFBVSxDQUFDLENBQUM7SUFDMUUsT0FBTztRQUNMLEdBQUcsY0FBYztRQUNqQixXQUFXLEVBQUUsVUFBVSxDQUFDLFdBQVc7UUFDbkMsT0FBTyxFQUFFLFVBQVUsQ0FBQyxPQUFPLENBQUMsR0FBRyxDQUFDLENBQUMsRUFBRSxNQUFNLEVBQUUsR0FBRyxTQUFTLEVBQUUsRUFBRSxFQUFFLENBQUMsU0FBUyxDQUFDO1FBQ3hFLGtCQUFrQixFQUFFLFVBQVUsQ0FBQyxrQkFBa0IsQ0FBQyxHQUFHLENBQUMsQ0FBQyxFQUFFLE1BQU0sRUFBRSxlQUFlLEVBQUUsYUFBYSxFQUFFLEdBQUcsVUFBVSxFQUFFLEVBQUUsRUFBRSxDQUFDLFVBQVUsQ0FBQztLQUNqSSxDQUFDO0FBQ0osQ0FBQztBQUVELE1BQU0sVUFBVSx3QkFBd0IsQ0FDdEMsY0FBb0MsRUFDcEMsTUFBNkI7SUFFN0IsSUFBSSxPQUFPLE1BQU0sS0FBSyxRQUFRLEVBQUUsQ0FBQztRQUMvQixNQUFNLGFBQWEsR0FBRyxNQUFNLENBQUMsSUFBSSxFQUFFLENBQUMsV0FBVyxFQUFFLENBQUM7UUFDbEQsT0FBTyxjQUFjLENBQUMsSUFBSSxDQUFDLENBQUMsU0FBUyxFQUFFLEVBQUUsQ0FBQyxTQUFTLENBQUMsSUFBSSxDQUFDLElBQUksRUFBRSxDQUFDLFdBQVcsRUFBRSxLQUFLLGFBQWEsQ0FBQyxDQUFDO0lBQ25HLENBQUM7SUFDRCxPQUFPLGNBQWMsQ0FBQyxJQUFJLENBQUMsQ0FBQyxTQUFTLEVBQUUsRUFBRSxDQUFDLFNBQVMsQ0FBQyxJQUFJLEtBQUssTUFBTSxJQUFJLENBQUMsU0FBUyxDQUFDLE9BQU8sQ0FBQyxDQUFDO0FBQzdGLENBQUM7QUFFRCxNQUFNLFVBQVUsK0JBQStCLENBQzdDLGNBQW9DO0lBRXBDLE1BQU0sZ0JBQWdCLEdBQUcsY0FBYyxDQUFDLE1BQU0sQ0FBQyxDQUFDLFNBQVMsRUFBRSxFQUFFLENBQUMsU0FBUyxDQUFDLE9BQU8sQ0FBQyxDQUFDO0lBQ2pGLElBQUksZ0JBQWdCLENBQUMsTUFBTSxHQUFHLENBQUMsRUFBRSxDQUFDO1FBQ2hDLE1BQU0sSUFBSSxLQUFLLENBQUMsMkNBQTJDLGdCQUFnQixDQUFDLEdBQUcsQ0FBQyxDQUFDLFNBQVMsRUFBRSxFQUFFLENBQUMsU0FBUyxDQUFDLElBQUksQ0FBQyxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsRUFBRSxDQUFDLENBQUM7SUFDL0gsQ0FBQztJQUNELE9BQU8sZ0JBQWdCLENBQUMsQ0FBQyxDQUFDO1dBQ3JCLGNBQWMsQ0FBQyxJQUFJLENBQUMsQ0FBQyxTQUFTLEVBQUUsRUFBRSxDQUFDLFNBQVMsQ0FBQyxJQUFJLEtBQUssS0FBSyxDQUFDO1dBQzVELGNBQWMsQ0FBQyxJQUFJLENBQUMsQ0FBQyxTQUFTLEVBQUUsRUFBRSxDQUFDLDJCQUEyQixDQUFDLFNBQVMsQ0FBQyxRQUFRLENBQUMsQ0FBQztXQUNuRixjQUFjLENBQUMsQ0FBQyxDQUFDLENBQUM7QUFDekIsQ0FBQztBQUVELE1BQU0sVUFBVSwyQkFBMkIsQ0FBQyxXQUFtQztJQUM3RSxPQUFPLFdBQVcsS0FBSyxNQUFNLElBQUksV0FBVyxLQUFLLE9BQU8sQ0FBQztBQUMzRCxDQUFDO0FBRUQsU0FBUywyQkFBMkIsQ0FDbEMsY0FBc0MsRUFDdEMsY0FBc0I7SUFFdEIsTUFBTSxlQUFlLEdBQUcsQ0FBQyxHQUFHLENBQUMsY0FBYyxDQUFDLFdBQVcsSUFBSSxFQUFFLENBQUMsQ0FBQyxDQUFDO0lBQ2hFLE1BQU0sYUFBYSxHQUFHLE1BQU0sQ0FBQyxjQUFjLENBQUMsS0FBSyxFQUFFLEdBQUcsQ0FBQyxDQUFDO0lBQ3hELElBQUksZUFBZSxDQUFDLE1BQU0sS0FBSyxDQUFDLElBQUksTUFBTSxDQUFDLFNBQVMsQ0FBQyxhQUFhLENBQUMsSUFBSSxhQUFhLEdBQUcsQ0FBQyxFQUFFLENBQUM7UUFDekYsZUFBZSxDQUFDLElBQUksQ0FBQztZQUNuQixJQUFJLEVBQUUsS0FBSztZQUNYLElBQUksRUFBRSxhQUFhO1lBQ25CLFFBQVEsRUFBRSxNQUFNO1lBQ2hCLE9BQU8sRUFBRSxJQUFJO1NBQ2QsQ0FBQyxDQUFDO0lBQ0wsQ0FBQztJQUNELElBQUksZUFBZSxDQUFDLE1BQU0sS0FBSyxDQUFDLEVBQUUsQ0FBQztRQUNqQyxPQUFPLEVBQUUsQ0FBQztJQUNaLENBQUM7SUFFRCxNQUFNLFNBQVMsR0FBRyxJQUFJLEdBQUcsRUFBVSxDQUFDO0lBQ3BDLE1BQU0sVUFBVSxHQUFHLElBQUksR0FBRyxFQUFVLENBQUM7SUFDckMsTUFBTSxpQkFBaUIsR0FBRyxlQUFlLENBQUMsR0FBRyxDQUFDLENBQUMsU0FBUyxFQUFFLEVBQUU7UUFDMUQsTUFBTSxJQUFJLEdBQUcsU0FBUyxDQUFDLElBQUksRUFBRSxJQUFJLEVBQUUsQ0FBQztRQUNwQyxJQUFJLENBQUMsSUFBSSxJQUFJLENBQUMsbUNBQW1DLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxFQUFFLENBQUM7WUFDN0QsTUFBTSxJQUFJLEtBQUssQ0FBQyw2QkFBNkIsU0FBUyxDQUFDLElBQUksUUFBUSxjQUFjLEVBQUUsQ0FBQyxDQUFDO1FBQ3ZGLENBQUM7UUFDRCxNQUFNLGNBQWMsR0FBRyxJQUFJLENBQUMsV0FBVyxFQUFFLENBQUM7UUFDMUMsSUFBSSxTQUFTLENBQUMsR0FBRyxDQUFDLGNBQWMsQ0FBQyxFQUFFLENBQUM7WUFDbEMsTUFBTSxJQUFJLEtBQUssQ0FBQywrQkFBK0IsSUFBSSxRQUFRLGNBQWMsRUFBRSxDQUFDLENBQUM7UUFDL0UsQ0FBQztRQUNELFNBQVMsQ0FBQyxHQUFHLENBQUMsY0FBYyxDQUFDLENBQUM7UUFDOUIsTUFBTSxJQUFJLEdBQUcsc0JBQXNCLENBQUMsU0FBUyxDQUFDLElBQUksRUFBRSxlQUFlLElBQUksT0FBTyxjQUFjLEVBQUUsQ0FBQyxDQUFDO1FBQ2hHLE1BQU0sT0FBTyxHQUFHLFNBQVMsQ0FBQyxPQUFPLEtBQUssU0FBUztZQUM3QyxDQUFDLENBQUMsU0FBUztZQUNYLENBQUMsQ0FBQyxzQkFBc0IsQ0FBQyxTQUFTLENBQUMsT0FBTyxFQUFFLG1CQUFtQixJQUFJLE9BQU8sY0FBYyxFQUFFLENBQUMsQ0FBQztRQUM5RixJQUFJLE9BQU8sS0FBSyxTQUFTLElBQUksT0FBTyxHQUFHLElBQUksRUFBRSxDQUFDO1lBQzVDLE1BQU0sSUFBSSxLQUFLLENBQUMsc0JBQXNCLElBQUksUUFBUSxjQUFjLG9CQUFvQixDQUFDLENBQUM7UUFDeEYsQ0FBQztRQUNELE1BQU0sUUFBUSxHQUFHLFNBQVMsQ0FBQyxRQUFRLElBQUksS0FBSyxDQUFDO1FBQzdDLE1BQU0sS0FBSyxHQUFHLEdBQUcsUUFBUSxJQUFJLElBQUksSUFBSSxPQUFPLElBQUksSUFBSSxFQUFFLENBQUM7UUFDdkQsSUFBSSxVQUFVLENBQUMsR0FBRyxDQUFDLEtBQUssQ0FBQyxFQUFFLENBQUM7WUFDMUIsTUFBTSxJQUFJLEtBQUssQ0FBQywrQkFBK0IsS0FBSyxPQUFPLGNBQWMsRUFBRSxDQUFDLENBQUM7UUFDL0UsQ0FBQztRQUNELFVBQVUsQ0FBQyxHQUFHLENBQUMsS0FBSyxDQUFDLENBQUM7UUFDdEIsT0FBTztZQUNMLEdBQUcsU0FBUztZQUNaLElBQUk7WUFDSixJQUFJO1lBQ0osT0FBTztZQUNQLFFBQVE7U0FDVCxDQUFDO0lBQ0osQ0FBQyxDQUFDLENBQUM7SUFFSCxJQUFJLENBQUMsaUJBQWlCLENBQUMsSUFBSSxDQUFDLENBQUMsU0FBUyxFQUFFLEVBQUUsQ0FBQyxTQUFTLENBQUMsT0FBTyxDQUFDLEVBQUUsQ0FBQztRQUM5RCxNQUFNLFNBQVMsR0FBRyxpQkFBaUIsQ0FBQyxJQUFJLENBQUMsQ0FBQyxTQUFTLEVBQUUsRUFBRSxDQUFDLFNBQVMsQ0FBQyxJQUFJLEtBQUssS0FBSyxDQUFDLENBQUM7UUFDbEYsSUFBSSxTQUFTLEVBQUUsQ0FBQztZQUNkLFNBQVMsQ0FBQyxPQUFPLEdBQUcsSUFBSSxDQUFDO1FBQzNCLENBQUM7SUFDSCxDQUFDO0lBRUQsT0FBTyxpQkFBaUIsQ0FBQztBQUMzQixDQUFDO0FBRUQsU0FBUywwQkFBMEIsQ0FDakMsU0FBOEIsRUFDOUIsY0FBb0MsRUFDcEMsb0JBQW9ELEVBQ3BELGNBQXNCLEVBQ3RCLFVBQXNEO0lBRXRELE1BQU0sVUFBVSxHQUFHLFNBQVMsQ0FBQyxJQUFJLElBQUksa0JBQWtCLENBQUM7SUFDeEQsSUFBSSxDQUFDLGNBQWMsQ0FBQyxNQUFNLEVBQUUsQ0FBQztRQUMzQixNQUFNLElBQUksS0FBSyxDQUFDLFVBQVUsVUFBVSxPQUFPLGNBQWMsNkNBQTZDLENBQUMsQ0FBQztJQUMxRyxDQUFDO0lBRUQsSUFBSSxTQUFTLENBQUMsVUFBVSxLQUFLLFNBQVMsRUFBRSxDQUFDO1FBQ3ZDLE1BQU0sTUFBTSxHQUFHLHdCQUF3QixDQUFDLGNBQWMsRUFBRSxTQUFTLENBQUMsVUFBVSxDQUFDLENBQUM7UUFDOUUsSUFBSSxDQUFDLE1BQU0sRUFBRSxDQUFDO1lBQ1osTUFBTSxJQUFJLEtBQUssQ0FBQyxVQUFVLFVBQVUsT0FBTyxjQUFjLHNDQUFzQyxTQUFTLENBQUMsVUFBVSxHQUFHLENBQUMsQ0FBQztRQUMxSCxDQUFDO1FBQ0QsT0FBTyxNQUFNLENBQUM7SUFDaEIsQ0FBQztJQUVELElBQUksU0FBUyxDQUFDLElBQUksS0FBSyxTQUFTLEVBQUUsQ0FBQztRQUNqQyxJQUFJLENBQUMsVUFBVSxDQUFDLHFCQUFxQixFQUFFLENBQUM7WUFDdEMsTUFBTSxJQUFJLEtBQUssQ0FBQyxVQUFVLFVBQVUsT0FBTyxjQUFjLDJDQUEyQyxDQUFDLENBQUM7UUFDeEcsQ0FBQztRQUNELE1BQU0sVUFBVSxHQUFHLE1BQU0sQ0FBQyxTQUFTLENBQUMsSUFBSSxDQUFDLENBQUM7UUFDMUMsTUFBTSxNQUFNLEdBQUcsd0JBQXdCLENBQUMsY0FBYyxFQUFFLFVBQVUsQ0FBQyxDQUFDO1FBQ3BFLElBQUksQ0FBQyxNQUFNLEVBQUUsQ0FBQztZQUNaLE1BQU0sSUFBSSxLQUFLLENBQUMsVUFBVSxVQUFVLE9BQU8sY0FBYyxzQ0FBc0MsU0FBUyxDQUFDLElBQUksRUFBRSxDQUFDLENBQUM7UUFDbkgsQ0FBQztRQUNELE9BQU8sTUFBTSxDQUFDO0lBQ2hCLENBQUM7SUFFRCxJQUFJLENBQUMsb0JBQW9CLEVBQUUsQ0FBQztRQUMxQixNQUFNLElBQUksS0FBSyxDQUFDLFVBQVUsVUFBVSxPQUFPLGNBQWMsc0RBQXNELENBQUMsQ0FBQztJQUNuSCxDQUFDO0lBQ0QsT0FBTyxvQkFBb0IsQ0FBQztBQUM5QixDQUFDO0FBRUQsU0FBUyxrQ0FBa0MsQ0FDekMsV0FBd0MsRUFDeEMsY0FBb0MsRUFDcEMsY0FBc0I7SUFFdEIsTUFBTSxTQUFTLEdBQUcsSUFBSSxHQUFHLEVBQVUsQ0FBQztJQUNwQyxNQUFNLGVBQWUsR0FBRyxJQUFJLEdBQUcsRUFBVSxDQUFDO0lBQzFDLE9BQU8sV0FBVyxDQUFDLEdBQUcsQ0FBQyxDQUFDLFVBQVUsRUFBRSxFQUFFO1FBQ3BDLE1BQU0sSUFBSSxHQUFHLFVBQVUsQ0FBQyxJQUFJLEVBQUUsSUFBSSxFQUFFLENBQUM7UUFDckMsSUFBSSxDQUFDLElBQUksSUFBSSxDQUFDLG1DQUFtQyxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsRUFBRSxDQUFDO1lBQzdELE1BQU0sSUFBSSxLQUFLLENBQUMscUNBQXFDLFVBQVUsQ0FBQyxJQUFJLFFBQVEsY0FBYyxFQUFFLENBQUMsQ0FBQztRQUNoRyxDQUFDO1FBQ0QsTUFBTSxjQUFjLEdBQUcsSUFBSSxDQUFDLFdBQVcsRUFBRSxDQUFDO1FBQzFDLElBQUksU0FBUyxDQUFDLEdBQUcsQ0FBQyxjQUFjLENBQUMsRUFBRSxDQUFDO1lBQ2xDLE1BQU0sSUFBSSxLQUFLLENBQUMsa0NBQWtDLElBQUksUUFBUSxjQUFjLEVBQUUsQ0FBQyxDQUFDO1FBQ2xGLENBQUM7UUFDRCxTQUFTLENBQUMsR0FBRyxDQUFDLGNBQWMsQ0FBQyxDQUFDO1FBQzlCLElBQUksVUFBVSxDQUFDLFNBQVMsS0FBSyxJQUFJLEVBQUUsQ0FBQztZQUNsQyxNQUFNLElBQUksS0FBSyxDQUFDLHdCQUF3QixJQUFJLFFBQVEsY0FBYyxvQkFBb0IsQ0FBQyxDQUFDO1FBQzFGLENBQUM7UUFDRCxJQUFJLENBQUMsQ0FBQyxLQUFLLEVBQUUsS0FBSyxDQUFDLENBQUMsUUFBUSxDQUFDLFVBQVUsQ0FBQyxRQUFRLENBQUMsRUFBRSxDQUFDO1lBQ2xELE1BQU0sSUFBSSxLQUFLLENBQUMsd0JBQXdCLElBQUksUUFBUSxjQUFjLDhCQUE4QixVQUFVLENBQUMsUUFBUSxHQUFHLENBQUMsQ0FBQztRQUMxSCxDQUFDO1FBQ0QsTUFBTSxNQUFNLEdBQUcsd0JBQXdCLENBQUMsY0FBYyxFQUFFLFVBQVUsQ0FBQyxVQUFVLENBQUMsQ0FBQztRQUMvRSxJQUFJLENBQUMsTUFBTSxFQUFFLENBQUM7WUFDWixNQUFNLElBQUksS0FBSyxDQUFDLHdCQUF3QixJQUFJLFFBQVEsY0FBYyxzQ0FBc0MsVUFBVSxDQUFDLFVBQVUsR0FBRyxDQUFDLENBQUM7UUFDcEksQ0FBQztRQUNELE1BQU0sVUFBVSxHQUFHLHNCQUFzQixDQUFDLFVBQVUsQ0FBQyxVQUFVLEVBQUUsZUFBZSxJQUFJLE9BQU8sY0FBYyxFQUFFLENBQUMsQ0FBQztRQUM3RyxNQUFNLFdBQVcsR0FBRyxNQUFNLENBQUMsSUFBSSxDQUFDO1FBQ2hDLE1BQU0sU0FBUyxHQUFHLE1BQU0sQ0FBQyxPQUFPLElBQUksTUFBTSxDQUFDLElBQUksQ0FBQztRQUNoRCxNQUFNLGFBQWEsR0FBRyxVQUFVLENBQUMsYUFBYSxLQUFLLFNBQVM7WUFDMUQsQ0FBQyxDQUFDLFVBQVUsR0FBRyxDQUFDLFNBQVMsR0FBRyxXQUFXLENBQUM7WUFDeEMsQ0FBQyxDQUFDLHNCQUFzQixDQUFDLFVBQVUsQ0FBQyxhQUFhLEVBQUUsbUJBQW1CLElBQUksT0FBTyxjQUFjLEVBQUUsQ0FBQyxDQUFDO1FBQ3JHLElBQUksYUFBYSxHQUFHLFVBQVUsRUFBRSxDQUFDO1lBQy9CLE1BQU0sSUFBSSxLQUFLLENBQUMsd0JBQXdCLElBQUksUUFBUSxjQUFjLHNDQUFzQyxDQUFDLENBQUM7UUFDNUcsQ0FBQztRQUNELElBQUksQ0FBQyxhQUFhLEdBQUcsVUFBVSxDQUFDLEtBQUssQ0FBQyxTQUFTLEdBQUcsV0FBVyxDQUFDLEVBQUUsQ0FBQztZQUMvRCxNQUFNLElBQUksS0FBSyxDQUFDLHdFQUF3RSxJQUFJLFFBQVEsY0FBYyxFQUFFLENBQUMsQ0FBQztRQUN4SCxDQUFDO1FBQ0QsS0FBSyxJQUFJLE1BQU0sR0FBRyxDQUFDLEVBQUUsTUFBTSxJQUFJLGFBQWEsR0FBRyxVQUFVLEVBQUUsTUFBTSxFQUFFLEVBQUUsQ0FBQztZQUNwRSxNQUFNLEdBQUcsR0FBRyxHQUFHLFVBQVUsQ0FBQyxRQUFRLElBQUksVUFBVSxHQUFHLE1BQU0sRUFBRSxDQUFDO1lBQzVELElBQUksZUFBZSxDQUFDLEdBQUcsQ0FBQyxHQUFHLENBQUMsRUFBRSxDQUFDO2dCQUM3QixNQUFNLElBQUksS0FBSyxDQUFDLHlCQUF5QixVQUFVLEdBQUcsTUFBTSxJQUFJLFVBQVUsQ0FBQyxRQUFRLE9BQU8sY0FBYyxFQUFFLENBQUMsQ0FBQztZQUM5RyxDQUFDO1lBQ0QsZUFBZSxDQUFDLEdBQUcsQ0FBQyxHQUFHLENBQUMsQ0FBQztRQUMzQixDQUFDO1FBQ0QsT0FBTztZQUNMLEdBQUcsVUFBVTtZQUNiLElBQUk7WUFDSixVQUFVO1lBQ1YsYUFBYTtZQUNiLFFBQVEsRUFBRSxVQUFVLENBQUMsUUFBUTtZQUM3QixNQUFNO1lBQ04sZUFBZSxFQUFFLFdBQVc7WUFDNUIsYUFBYSxFQUFFLFNBQVM7U0FDekIsQ0FBQztJQUNKLENBQUMsQ0FBQyxDQUFDLElBQUksQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDLEVBQUUsRUFBRTtRQUNmLE9BQU8sQ0FBQyxDQUFDLFFBQVEsQ0FBQyxhQUFhLENBQUMsQ0FBQyxDQUFDLFFBQVEsQ0FBQztlQUN0QyxDQUFDLENBQUMsVUFBVSxHQUFHLENBQUMsQ0FBQyxVQUFVO2VBQzNCLENBQUMsQ0FBQyxJQUFJLENBQUMsYUFBYSxDQUFDLENBQUMsQ0FBQyxJQUFJLENBQUMsQ0FBQztJQUNwQyxDQUFDLENBQUMsQ0FBQztBQUNMLENBQUM7QUFFRCxTQUFTLHNCQUFzQixDQUFDLE9BQWUsRUFBRSxRQUFnQjtJQUMvRCxNQUFNLElBQUksR0FBRyxNQUFNLENBQUMsT0FBTyxDQUFDLENBQUM7SUFDN0IsSUFBSSxDQUFDLE1BQU0sQ0FBQyxTQUFTLENBQUMsSUFBSSxDQUFDLElBQUksSUFBSSxHQUFHLENBQUMsSUFBSSxJQUFJLEdBQUcsS0FBSyxFQUFFLENBQUM7UUFDeEQsTUFBTSxJQUFJLEtBQUssQ0FBQyxXQUFXLFFBQVEsS0FBSyxPQUFPLDRDQUE0QyxDQUFDLENBQUM7SUFDL0YsQ0FBQztJQUNELE9BQU8sSUFBSSxDQUFDO0FBQ2QsQ0FBQyJ9

package/dist_ts/data/traffic.d.ts

@@ -1,4 +1,11 @@
 import * as plugins from '../plugins.js';
 interface IReverseProxyConfig extends plugins.tsclass.network.IReverseProxyConfig {
 }
+export interface ICoretrafficPortRouteConfig {
+    name: string;
+    listenPort: number;
+    transport: 'tcp' | 'udp';
+    destinationIps: string[];
+    destinationPort: number;
+}
 export { type IReverseProxyConfig };

package/dist_ts/data/traffic.js

@@ -1,3 +1,3 @@
 import * as plugins from '../plugins.js';
 export {};
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHJhZmZpYy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvdHJhZmZpYy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUl6QyxPQUFPLEVBQTRCLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHJhZmZpYy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvdHJhZmZpYy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQVl6QyxPQUFPLEVBQTRCLENBQUMifQ==

package/dist_ts/requests/routing.d.ts

@@ -1,8 +1,9 @@
-import { type IReverseProxyConfig } from '../data/traffic.js';
+import { type ICoretrafficPortRouteConfig, type IReverseProxyConfig } from '../data/traffic.js';
 export interface IRequest_Coreflow_Coretraffic_RoutingUpdate {
     method: 'updateRouting';
     request: {
         reverseConfigs: IReverseProxyConfig[];
+        portRoutes?: ICoretrafficPortRouteConfig[];
     };
     response: {
         status: 'ok' | 'error';
@@ -19,6 +20,7 @@ export interface IRequest_Coretraffic_Coreflow_GetCurrentRouting {
     request: Record<string, never>;
     response: {
         reverseConfigs: IReverseProxyConfig[];
+        portRoutes?: ICoretrafficPortRouteConfig[];
     };
 }
 /**

package/dist_ts/requests/routing.js

@@ -1,2 +1,2 @@
 import {} from '../data/traffic.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicm91dGluZy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3JlcXVlc3RzL3JvdXRpbmcudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUE0QixNQUFNLG9CQUFvQixDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicm91dGluZy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3JlcXVlc3RzL3JvdXRpbmcudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUE4RCxNQUFNLG9CQUFvQixDQUFDIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "7.28.0",
+  "version": "8.0.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -17,7 +17,7 @@
   "devDependencies": {
     "@git.zone/tsbuild": "^4.4.2",
     "@git.zone/tsdoc": "^2.1.1",
-    "@git.zone/tsrun": "^2.0.4",
+    "@git.zone/tsrun": "^2.0.5",
     "@git.zone/tstest": "^3.6.6",
     "@types/node": "^25.9.2"
   },

package/readme.md

@@ -52,13 +52,36 @@ const service: data.IService = {
     deploymentStrategy: 'limited-replicas',
     scaleFactor: 2,
     balancingStrategy: 'round-robin',
+    targetPorts: [
+      {
+        name: 'web',
+        port: 3000,
+        protocol: 'http',
+        default: true,
+      },
+      {
+        name: 'ssh',
+        port: 2222,
+        protocol: 'ssh',
+      },
+    ],
     ports: {
-      web: 3000,
+      web: 3000, // legacy compatibility shorthand during migration
     },
     domains: [
       {
         name: 'api',
         protocol: 'https',
+        targetPort: 'web',
+      },
+    ],
+    publicPortMappings: [
+      {
+        name: 'ssh-public',
+        publicPort: 2222,
+        targetPort: 'ssh',
+        protocol: 'tcp',
+        exclusive: true,
       },
     ],
     deploymentIds: [],
@@ -70,13 +93,29 @@ Common data contracts include:
 
 - `ICluster` and `IClusterNode` for cluster membership and provisioning state.
 - `IService`, `IDeployment`, `IImage`, `IRegistryTarget`, and `IExternalRegistry` for workload delivery.
+- Service port contracts including `IServiceTargetPort`, `IServiceDomainRoute`, and `IServicePublicPortMapping` for canonical backend targets, domain target references, and edge/Coretraffic TCP/UDP public exposure.
 - `IDomain`, `IDnsEntry`, and traffic contracts for routing and DNS management.
+- Traffic and gateway route contracts including `ICoretrafficPortRouteConfig`, routing `portRoutes`, gateway route `routeRef` ownership, optional match `domains`, `transport`, and `remoteIngress` route intent.
 - `ISecretBundle` and `ISecretGroup` for secret ownership and shared secret groups.
 - Mail gateway contracts for domain authorities, address bindings, WorkApp bindings, managed SMTP/API credentials, spool items, delivery journals, and inbound/outbound message payloads.
 - Service-level mail configuration through `IService.data.mail`, including per-address inbound `smtpForward` settings and outbound credential metadata. Cloudly settings include dcrouter gateway, SMTP submission, and inbound forward-target keys for reconciling those bindings.
 - `IUser`, `IIdentity`, and token-related contracts for authentication context.
 - `ICloudlyConfig`, `ICloudlySettings`, status, server, bare-metal, BaseOS, backup, and task execution interfaces for control-plane state.
 
+Shared service port helpers are exported from `data` so Cloudly, App Store resolution, Coreflow, Coretraffic, Onebox, and dcrouter agree on the same normalization rules:
+
+```typescript
+const normalizedPorts = data.normalizeServicePortConfig(service.data);
+const defaultTarget = data.resolveDefaultServiceTargetPort(normalizedPorts.targetPorts);
+const webTarget = data.resolveServiceTargetPort(normalizedPorts.targetPorts, 'web');
+
+if (webTarget && data.isHttpServiceTargetProtocol(webTarget.protocol)) {
+  // safe to use as a domain route target
+}
+```
+
+`normalizeServicePortData()` returns service data with canonical `targetPorts`, domain `targetPort` refs, and `publicPortMappings` while removing legacy domain `port` fields from normalized writes.
+
 ## TypedRequest Contracts
 
 Use `requests` when registering handlers with `@api.global/typedrequest` or when creating typed requests through a TypedSocket client.
@@ -111,16 +150,19 @@ Request groups are exported by product area:
 - `requests.certificate`
 - `requests.cluster`
 - `requests.config`
+- `requests.corestore`
 - `requests.deployment`
 - `requests.dns`
 - `requests.domain`
 - `requests.externalRegistry`
+- `requests.gateway`
 - `requests.hostedapp`
 - `requests.identity`
 - `requests.image`
 - `requests.inform`
 - `requests.log`
 - `requests.mail`
+- `requests.migration`
 - `requests.network`
 - `requests.node`
 - `requests.platform`
@@ -181,7 +223,7 @@ Good candidates for this package:
 Poor candidates for this package:
 
 - Private implementation details of one service.
-- Runtime helpers or convenience wrappers.
+- Runtime helpers or convenience wrappers, unless they are shared contract normalization or validation helpers used by multiple packages.
 - Compatibility aliases without an active consumer.
 
 ## Development

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '7.28.0',
+  version: '8.0.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/appstore/types.ts

@@ -1,3 +1,9 @@
+import type {
+  IServiceDomainRoute,
+  IServicePublicPortMapping,
+  IServiceTargetPort,
+} from '../data/serviceports.js';
+
 export type TAppStorePlatformRequirement = 'mongodb' | 's3' | 'clickhouse' | 'valkey' | 'mariadb';
 export type TAppStoreSourceType = 'inline' | 'repoManifest' | 'dockerImage';
 export type TAppStoreTrackingMode = 'tag' | 'digest';
@@ -114,7 +120,12 @@ export interface IAppStoreAppMeta {
 
 export interface IAppStoreVersionConfig {
   image: string;
-  port: number;
+  /** Legacy shorthand for targetPorts.web. New templates should prefer targetPorts. */
+  port?: number;
+  targetPorts?: IServiceTargetPort[];
+  domains?: IServiceDomainRoute[];
+  /** Edge/coretraffic public TCP/UDP exposure, distinct from Docker publishedPorts. */
+  publicPortMappings?: IServicePublicPortMapping[];
   envVars?: IAppStoreEnvVar[];
   volumes?: TAppStoreVolumeSpec[];
   publishedPorts?: IAppStorePublishedPort[];
@@ -175,8 +186,10 @@ export interface IAppStoreInstallRequest {
   version?: string;
   serviceName: string;
   domain?: string;
+  /** Legacy install-time override for the web target port. */
   port?: number;
   publishedPorts?: IAppStorePublishedPort[];
+  publicPortMappings?: IServicePublicPortMapping[];
   envVars?: Record<string, string>;
 }
 

package/ts/data/gateway.ts

@@ -185,7 +185,10 @@ export interface IGatewayClientOwnership {
   gatewayClientId?: string;
   /** App identifier within the owning gateway client platform. */
   appId: string;
-  hostname: string;
+  /** Hostname ownership for domain routes. Preserved for existing route keys. */
+  hostname?: string;
+  /** Stable non-domain route key, for example public-port mapping exposure refs. */
+  routeRef?: string;
 }
 
 /**
@@ -201,7 +204,8 @@ export interface IGatewayRouteTarget {
  */
 export interface IGatewayRouteMatch {
   ports: number[];
-  domains: string[];
+  domains?: string[];
+  transport?: 'tcp' | 'udp' | 'all';
   path?: string;
 }
 
@@ -237,6 +241,10 @@ export interface IGatewayRouteConfig {
   name: string;
   match: IGatewayRouteMatch;
   action: IGatewayRouteAction;
+  remoteIngress?: {
+    enabled: boolean;
+    edgeFilter?: string[];
+  };
 }
 
 /**

package/ts/data/index.ts

@@ -21,6 +21,7 @@ export * from './backup.js';
 export * from './clusternode.js';
 export * from './settings.js';
 export * from './service.js';
+export * from './serviceports.js';
 export * from './status.js';
 export * from './taskexecution.js';
 export * from './traffic.js';

package/ts/data/service.ts

@@ -3,6 +3,11 @@ import type { IRegistryTarget } from './registry.js';
 import type { IAppStorePublishedPort } from '../appstore/index.js';
 import type { IHostedAppLifecycleState } from './hostedapp.js';
 import type { IServiceMailConfig } from './mail.js';
+import type {
+  IServiceDomainRoute,
+  IServicePublicPortMapping,
+  IServiceTargetPort,
+} from './serviceports.js';
 
 export interface IServiceVolume {
   /** Stable Docker volume name. If omitted, Coreflow derives one from service id and mount path. */
@@ -119,38 +124,30 @@ export interface IService {
     
     scaleFactor: number;
     balancingStrategy: 'round-robin' | 'least-connections';
+    /**
+     * Canonical backend/container ports for this service. New domain routes
+     * and public mappings reference these targets by name or exact port.
+     */
+    targetPorts?: IServiceTargetPort[];
     ports: {
+      /**
+       * Legacy main backend port. New writes should declare targetPorts and
+       * keep this only as compatibility shorthand during migration.
+       */
       web: number;
+      /**
+       * Legacy implicit domain-to-port routes. Runtime code must not treat
+       * this as a permissive routing source for new services.
+       */
       custom?: { [domain: string]: string };
     };
     mail?: IServiceMailConfig;
     volumes?: IServiceVolume[];
     publishedPorts?: IAppStorePublishedPort[];
+    /** Edge/coretraffic public TCP/UDP exposure, distinct from Docker Swarm publishedPorts. */
+    publicPortMappings?: IServicePublicPortMapping[];
     resources?: IServiceRessources;
-    domains: {
-      /**
-       * Optional domain ID to specify which domain to use
-       * If not specified, will use the default domain or require manual configuration
-       */
-      domainId?: string;
-      /**
-       * The subdomain name (e.g., 'api', 'www', '@' for root)
-       */
-      name: string;
-      /**
-       * The port to expose (defaults to ports.web if not specified)
-       */
-      port?: number;
-      /**
-       * The protocol for this domain entry
-       */
-      protocol?: 'http' | 'https' | 'ssh';
-      /**
-       * Gateway source profile for this domain's route (e.g. 'standard'
-       * for internal-only access). Defaults to the gateway's public profile.
-       */
-      sourceProfileRef?: string;
-    }[];
+    domains: IServiceDomainRoute[];
     deploymentIds: string[];
   };
 }

package/ts/data/serviceports.ts

@@ -0,0 +1,338 @@
+export type TServiceTargetProtocol =
+  | 'http'
+  | 'https'
+  | 'ssh'
+  | 'tcp'
+  | 'udp'
+  | `custom:${string}`;
+
+export type TServiceTargetPortRef = string | number;
+
+export interface IServiceTargetPort {
+  name: string;
+  port: number;
+  portEnd?: number;
+  protocol: TServiceTargetProtocol;
+  description?: string;
+  default?: boolean;
+}
+
+export interface IServiceDomainRoute {
+  domainId?: string;
+  name: string;
+  targetPort?: TServiceTargetPortRef;
+  /**
+   * Legacy backend target port. New writes must use targetPort.
+   */
+  port?: number;
+  protocol?: 'http' | 'https';
+  sourceProfileRef?: string;
+}
+
+export interface IServicePublicPortMapping {
+  name: string;
+  publicPort: number;
+  publicPortEnd?: number;
+  targetPort: TServiceTargetPortRef;
+  protocol: 'tcp' | 'udp';
+  sourceProfileRef?: string;
+  exclusive: true;
+}
+
+export interface IResolvedServiceDomainRoute extends IServiceDomainRoute {
+  targetPort: TServiceTargetPortRef;
+  target: IServiceTargetPort;
+}
+
+export interface IResolvedServicePublicPortMapping extends IServicePublicPortMapping {
+  target: IServiceTargetPort;
+  targetPortStart: number;
+  targetPortEnd: number;
+  publicPortEnd: number;
+}
+
+export interface IServicePortSourceData {
+  name?: string;
+  ports?: {
+    web?: number;
+    custom?: Record<string, string>;
+  };
+  targetPorts?: IServiceTargetPort[];
+  domains?: IServiceDomainRoute[];
+  publicPortMappings?: IServicePublicPortMapping[];
+}
+
+export interface INormalizedServicePortConfig {
+  targetPorts: IServiceTargetPort[];
+  defaultTargetPort?: IServiceTargetPort;
+  domains: IResolvedServiceDomainRoute[];
+  publicPortMappings: IResolvedServicePublicPortMapping[];
+}
+
+export interface IServicePortNormalizationOptions {
+  /**
+   * Accept legacy domains[].port only when it resolves to a declared target.
+   * Defaults to true for staged migration reads.
+   */
+  allowLegacyDomainPort?: boolean;
+  /**
+   * Domain routes are HTTP(S) virtual-host routes. Defaults to true.
+   */
+  requireHttpDomainTargets?: boolean;
+}
+
+export function normalizeServicePortConfig(
+  serviceDataArg: IServicePortSourceData,
+  optionsArg: IServicePortNormalizationOptions = {},
+): INormalizedServicePortConfig {
+  const options: Required<IServicePortNormalizationOptions> = {
+    allowLegacyDomainPort: optionsArg.allowLegacyDomainPort ?? true,
+    requireHttpDomainTargets: optionsArg.requireHttpDomainTargets ?? true,
+  };
+  const serviceName = serviceDataArg.name || 'service';
+  const targetPorts = normalizeServiceTargetPorts(serviceDataArg, serviceName);
+  const defaultTargetPort = resolveDefaultServiceTargetPort(targetPorts);
+  const domains = (serviceDataArg.domains || []).map((domainArg) => {
+    const target = resolveServiceDomainTarget(domainArg, targetPorts, defaultTargetPort, serviceName, options);
+    if (options.requireHttpDomainTargets && !isHttpServiceTargetProtocol(target.protocol)) {
+      throw new Error(`Domain ${domainArg.name} on ${serviceName} references non-HTTP target '${target.name}' (${target.protocol})`);
+    }
+    if (target.portEnd && target.portEnd !== target.port) {
+      throw new Error(`Domain ${domainArg.name} on ${serviceName} references ranged target '${target.name}'`);
+    }
+    const normalizedDomain: IResolvedServiceDomainRoute = {
+      ...domainArg,
+      targetPort: domainArg.targetPort ?? target.name,
+      target,
+    };
+    delete normalizedDomain.port;
+    return normalizedDomain;
+  });
+  const publicPortMappings = normalizeServicePublicPortMappings(
+    serviceDataArg.publicPortMappings || [],
+    targetPorts,
+    serviceName,
+  );
+  return {
+    targetPorts,
+    defaultTargetPort,
+    domains,
+    publicPortMappings,
+  };
+}
+
+export function normalizeServicePortData<T extends IServicePortSourceData>(
+  serviceDataArg: T,
+  optionsArg: IServicePortNormalizationOptions = {},
+): T & {
+  targetPorts: IServiceTargetPort[];
+  domains?: IServiceDomainRoute[];
+  publicPortMappings?: IServicePublicPortMapping[];
+} {
+  const normalized = normalizeServicePortConfig(serviceDataArg, optionsArg);
+  return {
+    ...serviceDataArg,
+    targetPorts: normalized.targetPorts,
+    domains: normalized.domains.map(({ target, ...domainArg }) => domainArg),
+    publicPortMappings: normalized.publicPortMappings.map(({ target, targetPortStart, targetPortEnd, ...mappingArg }) => mappingArg),
+  };
+}
+
+export function resolveServiceTargetPort(
+  targetPortsArg: IServiceTargetPort[],
+  refArg: TServiceTargetPortRef,
+): IServiceTargetPort | undefined {
+  if (typeof refArg === 'string') {
+    const normalizedRef = refArg.trim().toLowerCase();
+    return targetPortsArg.find((targetArg) => targetArg.name.trim().toLowerCase() === normalizedRef);
+  }
+  return targetPortsArg.find((targetArg) => targetArg.port === refArg && !targetArg.portEnd);
+}
+
+export function resolveDefaultServiceTargetPort(
+  targetPortsArg: IServiceTargetPort[],
+): IServiceTargetPort | undefined {
+  const explicitDefaults = targetPortsArg.filter((targetArg) => targetArg.default);
+  if (explicitDefaults.length > 1) {
+    throw new Error(`Multiple default target ports declared: ${explicitDefaults.map((targetArg) => targetArg.name).join(', ')}`);
+  }
+  return explicitDefaults[0]
+    || targetPortsArg.find((targetArg) => targetArg.name === 'web')
+    || targetPortsArg.find((targetArg) => isHttpServiceTargetProtocol(targetArg.protocol))
+    || targetPortsArg[0];
+}
+
+export function isHttpServiceTargetProtocol(protocolArg: TServiceTargetProtocol): boolean {
+  return protocolArg === 'http' || protocolArg === 'https';
+}
+
+function normalizeServiceTargetPorts(
+  serviceDataArg: IServicePortSourceData,
+  serviceNameArg: string,
+): IServiceTargetPort[] {
+  const declaredTargets = [...(serviceDataArg.targetPorts || [])];
+  const legacyWebPort = Number(serviceDataArg.ports?.web);
+  if (declaredTargets.length === 0 && Number.isInteger(legacyWebPort) && legacyWebPort > 0) {
+    declaredTargets.push({
+      name: 'web',
+      port: legacyWebPort,
+      protocol: 'http',
+      default: true,
+    });
+  }
+  if (declaredTargets.length === 0) {
+    return [];
+  }
+
+  const seenNames = new Set<string>();
+  const seenTuples = new Set<string>();
+  const normalizedTargets = declaredTargets.map((targetArg) => {
+    const name = targetArg.name?.trim();
+    if (!name || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,62}$/.test(name)) {
+      throw new Error(`Invalid target port name '${targetArg.name}' on ${serviceNameArg}`);
+    }
+    const normalizedName = name.toLowerCase();
+    if (seenNames.has(normalizedName)) {
+      throw new Error(`Duplicate target port name '${name}' on ${serviceNameArg}`);
+    }
+    seenNames.add(normalizedName);
+    const port = assertValidServicePort(targetArg.port, `target port ${name} on ${serviceNameArg}`);
+    const portEnd = targetArg.portEnd === undefined
+      ? undefined
+      : assertValidServicePort(targetArg.portEnd, `target port end ${name} on ${serviceNameArg}`);
+    if (portEnd !== undefined && portEnd < port) {
+      throw new Error(`target port range '${name}' on ${serviceNameArg} must be ascending`);
+    }
+    const protocol = targetArg.protocol || 'tcp';
+    const tuple = `${protocol}:${port}:${portEnd || port}`;
+    if (seenTuples.has(tuple)) {
+      throw new Error(`Duplicate target port tuple ${tuple} on ${serviceNameArg}`);
+    }
+    seenTuples.add(tuple);
+    return {
+      ...targetArg,
+      name,
+      port,
+      portEnd,
+      protocol,
+    };
+  });
+
+  if (!normalizedTargets.some((targetArg) => targetArg.default)) {
+    const webTarget = normalizedTargets.find((targetArg) => targetArg.name === 'web');
+    if (webTarget) {
+      webTarget.default = true;
+    }
+  }
+
+  return normalizedTargets;
+}
+
+function resolveServiceDomainTarget(
+  domainArg: IServiceDomainRoute,
+  targetPortsArg: IServiceTargetPort[],
+  defaultTargetPortArg: IServiceTargetPort | undefined,
+  serviceNameArg: string,
+  optionsArg: Required<IServicePortNormalizationOptions>,
+): IServiceTargetPort {
+  const domainName = domainArg.name || '(unnamed domain)';
+  if (!targetPortsArg.length) {
+    throw new Error(`Domain ${domainName} on ${serviceNameArg} requires at least one declared target port`);
+  }
+
+  if (domainArg.targetPort !== undefined) {
+    const target = resolveServiceTargetPort(targetPortsArg, domainArg.targetPort);
+    if (!target) {
+      throw new Error(`Domain ${domainName} on ${serviceNameArg} references undeclared targetPort '${domainArg.targetPort}'`);
+    }
+    return target;
+  }
+
+  if (domainArg.port !== undefined) {
+    if (!optionsArg.allowLegacyDomainPort) {
+      throw new Error(`Domain ${domainName} on ${serviceNameArg} uses legacy port; use targetPort instead`);
+    }
+    const legacyPort = Number(domainArg.port);
+    const target = resolveServiceTargetPort(targetPortsArg, legacyPort);
+    if (!target) {
+      throw new Error(`Domain ${domainName} on ${serviceNameArg} references undeclared legacy port ${domainArg.port}`);
+    }
+    return target;
+  }
+
+  if (!defaultTargetPortArg) {
+    throw new Error(`Domain ${domainName} on ${serviceNameArg} has no targetPort and no default target port exists`);
+  }
+  return defaultTargetPortArg;
+}
+
+function normalizeServicePublicPortMappings(
+  mappingsArg: IServicePublicPortMapping[],
+  targetPortsArg: IServiceTargetPort[],
+  serviceNameArg: string,
+): IResolvedServicePublicPortMapping[] {
+  const seenNames = new Set<string>();
+  const seenPublicPorts = new Set<string>();
+  return mappingsArg.map((mappingArg) => {
+    const name = mappingArg.name?.trim();
+    if (!name || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,62}$/.test(name)) {
+      throw new Error(`Invalid public port mapping name '${mappingArg.name}' on ${serviceNameArg}`);
+    }
+    const normalizedName = name.toLowerCase();
+    if (seenNames.has(normalizedName)) {
+      throw new Error(`Duplicate public port mapping '${name}' on ${serviceNameArg}`);
+    }
+    seenNames.add(normalizedName);
+    if (mappingArg.exclusive !== true) {
+      throw new Error(`Public port mapping '${name}' on ${serviceNameArg} must be exclusive`);
+    }
+    if (!['tcp', 'udp'].includes(mappingArg.protocol)) {
+      throw new Error(`Public port mapping '${name}' on ${serviceNameArg} has unsupported protocol '${mappingArg.protocol}'`);
+    }
+    const target = resolveServiceTargetPort(targetPortsArg, mappingArg.targetPort);
+    if (!target) {
+      throw new Error(`Public port mapping '${name}' on ${serviceNameArg} references undeclared targetPort '${mappingArg.targetPort}'`);
+    }
+    const publicPort = assertValidServicePort(mappingArg.publicPort, `public port ${name} on ${serviceNameArg}`);
+    const targetStart = target.port;
+    const targetEnd = target.portEnd || target.port;
+    const publicPortEnd = mappingArg.publicPortEnd === undefined
+      ? publicPort + (targetEnd - targetStart)
+      : assertValidServicePort(mappingArg.publicPortEnd, `public port end ${name} on ${serviceNameArg}`);
+    if (publicPortEnd < publicPort) {
+      throw new Error(`Public port mapping '${name}' on ${serviceNameArg} must have an ascending public range`);
+    }
+    if ((publicPortEnd - publicPort) !== (targetEnd - targetStart)) {
+      throw new Error(`Public and target port ranges must have the same length for mapping '${name}' on ${serviceNameArg}`);
+    }
+    for (let offset = 0; offset <= publicPortEnd - publicPort; offset++) {
+      const key = `${mappingArg.protocol}:${publicPort + offset}`;
+      if (seenPublicPorts.has(key)) {
+        throw new Error(`Duplicate public port ${publicPort + offset}/${mappingArg.protocol} on ${serviceNameArg}`);
+      }
+      seenPublicPorts.add(key);
+    }
+    return {
+      ...mappingArg,
+      name,
+      publicPort,
+      publicPortEnd,
+      protocol: mappingArg.protocol,
+      target,
+      targetPortStart: targetStart,
+      targetPortEnd: targetEnd,
+    };
+  }).sort((a, b) => {
+    return a.protocol.localeCompare(b.protocol)
+      || a.publicPort - b.publicPort
+      || a.name.localeCompare(b.name);
+  });
+}
+
+function assertValidServicePort(portArg: number, labelArg: string): number {
+  const port = Number(portArg);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid ${labelArg}: ${portArg}. Expected an integer between 1 and 65535.`);
+  }
+  return port;
+}

package/ts/data/traffic.ts

@@ -2,4 +2,12 @@ import * as plugins from '../plugins.js';
 
 interface IReverseProxyConfig extends plugins.tsclass.network.IReverseProxyConfig {}
 
+export interface ICoretrafficPortRouteConfig {
+  name: string;
+  listenPort: number;
+  transport: 'tcp' | 'udp';
+  destinationIps: string[];
+  destinationPort: number;
+}
+
 export { type IReverseProxyConfig };

package/ts/requests/routing.ts

@@ -1,9 +1,10 @@
-import { type IReverseProxyConfig } from '../data/traffic.js';
+import { type ICoretrafficPortRouteConfig, type IReverseProxyConfig } from '../data/traffic.js';
 
 export interface IRequest_Coreflow_Coretraffic_RoutingUpdate {
   method: 'updateRouting';
   request: {
     reverseConfigs: IReverseProxyConfig[];
+    portRoutes?: ICoretrafficPortRouteConfig[];
   };
   response: {
     status: 'ok' | 'error';
@@ -21,6 +22,7 @@ export interface IRequest_Coretraffic_Coreflow_GetCurrentRouting {
   request: Record<string, never>;
   response: {
     reverseConfigs: IReverseProxyConfig[];
+    portRoutes?: ICoretrafficPortRouteConfig[];
   };
 }