sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ ECS/ Service.ts

import * as ec2 from "@distilled.cloud/aws/ec2";
import * as ecs from "@distilled.cloud/aws/ecs";
import * as elbv2 from "@distilled.cloud/aws/elastic-load-balancing-v2";
import * as iam from "@distilled.cloud/aws/iam";
import type { Region } from "@distilled.cloud/aws/Region";
import { deepEqual, isResolved } from "alchemy/Diff";
import type { DnsConfig } from "alchemy/DNS/Adapter";
import * as Namespace from "alchemy/Namespace";
import * as Output from "alchemy/Output";
import { createPhysicalName } from "alchemy/PhysicalName";
import { Platform, type Main, type PlatformProps } from "alchemy/Platform";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import type { HostRuntimeContext, ServerHost } from "alchemy/Runtime/Process";
import { Stack } from "alchemy/Stack";
import { createInternalTags, diffTags } from "alchemy/Tags";
import { toMillis, toWireSeconds } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import type { HttpClient } from "effect/http/HttpClient";
import * as Option from "effect/Option";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { ScalableTarget } from "../ApplicationAutoScaling/ScalableTarget.ts";
import { ScalingPolicy } from "../ApplicationAutoScaling/ScalingPolicy.ts";
import { Service as CloudMapService } from "../CloudMap/Service.ts";
import type { Credentials } from "../Credentials.ts";
import { domainCertificate, isRoute53Dns, resolveDomainDns } from "../CustomDomain.ts";
import {
  SecurityGroup,
  type SecurityGroupId,
  type SecurityGroupRuleData,
} from "../EC2/SecurityGroup.ts";
import type { SubnetId } from "../EC2/Subnet.ts";
import type { VpcId } from "../EC2/Vpc.ts";
import {
  makeBunBootstrap,
  makeImageSource,
  type BundledImageSource,
  type DockerfileImageSource,
  type ImageSourceLike,
  type RegistryImageSource,
} from "../ECR/ImageSource.ts";
import type { ListenerAction, ListenerRuleCondition } from "../ELBv2/common.ts";
import { Listener } from "../ELBv2/Listener.ts";
import { ListenerRule } from "../ELBv2/ListenerRule.ts";
import { LoadBalancer } from "../ELBv2/LoadBalancer.ts";
import { TargetGroup, type TargetGroupArn } from "../ELBv2/TargetGroup.ts";
import { AWSEnvironment, type AccountID } from "../Environment.ts";
import { plainJson } from "../internal/Observe.ts";
import { syncLogGroupRetention, type LogRetentionConfig } from "../Logs/LogRetention.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";
import { findPublicHostedZoneId } from "../Route53/HostedZoneLookup.ts";
import type { ClusterArn } from "./Cluster.ts";
import {
  attachTaskBindings,
  createContainerRuntimeContext,
  createTaskRoleIfNotExists,
  deleteTaskDefinitionInfrastructure,
  ensureTaskExecutionRole,
  ensureTaskLogGroup,
  reapSupersededTaskDefinitionRevision,
  registerTaskDefinitionRevision,
  syncEnvironmentFilesPolicy,
  syncTaskDefinitionTags,
  taskImagePlatform,
  type TaskBindingContract,
  type TaskDefinitionConfig,
} from "./Task.ts";

export type ServiceName = string;
export type ServiceArn = `arn:aws:ecs:${RegionID}:${AccountID}:service/${string}/${ServiceName}`;

export const isService = (value: any): value is Service =>
  typeof value === "object" &&
  value !== null &&
  "Type" in value &&
  value.Type === "AWS.ECS.Service";

// ───────────────────────────────────────────────────────────────────────────
// Managed load balancer (owned + shared) — types
// ───────────────────────────────────────────────────────────────────────────

/** ALB (layer-7) listener protocols. */
export type ServiceApplicationProtocol = "http" | "https";

/** NLB (layer-4) listener protocols. */
export type ServiceNetworkProtocol = "tcp" | "udp" | "tcp_udp" | "tls";

/**
 * Listener protocols supported by managed service ingress. `http`/`https`
 * compose an Application Load Balancer; `tcp`/`udp`/`tcp_udp`/`tls` compose a
 * Network Load Balancer. Mixing the two families in one service is a typed
 * error ({@link MixedLoadBalancerProtocols}).
 */
export type ServiceListenerProtocol = ServiceApplicationProtocol | ServiceNetworkProtocol;

const NETWORK_PROTOCOLS: ReadonlySet<string> = new Set(["tcp", "udp", "tcp_udp", "tls"]);

/** A `"80/http"`-style port/protocol spec. */
export type ServiceListenSpec = `${number}/${ServiceListenerProtocol}`;

/**
 * A routing rule for the service's managed load balancer. Conditions are FLAT
 * on the rule (no `conditions: {}` wrapper) and are AND-ed together; a rule
 * with no conditions matches every request (`path: "/*"` on a shared
 * listener, or becomes the owned listener's default action).
 */
export interface ServiceLoadBalancerRule {
  /**
   * Where the rule listens. A `"80/http"`-style string means the service OWNS
   * the listener (and its ALB); an `ELBv2.Listener` reference means the rule
   * attaches to that existing (shared) listener. Omitting it falls back to
   * the config-level `listener` (shared) or the service's default owned
   * listener. Mixing owned strings and shared references within one service
   * is a typed error ({@link MixedListenerOwnership}).
   */
  listen?: ServiceListenSpec | Listener;
  /**
   * Forward matched requests to the container at this port/protocol. A target
   * group is created per distinct `forward` + `container` pair.
   * @default the main container's port
   */
  forward?: ServiceListenSpec;
  /**
   * Redirect matched requests (HTTP 301) to this port/protocol. Mutually
   * exclusive with {@link forward}.
   */
  redirect?: ServiceListenSpec;
  /**
   * Name of the container receiving traffic — the main container by default,
   * or a sidecar's container name.
   */
  container?: string;
  /** Match on the request path (`*` and `?` wildcards). */
  path?: string | string[];
  /** Match on the `Host` header (`*` and `?` wildcards). */
  host?: string | string[];
  /** Match on a named HTTP header. */
  header?: { name: string; values: string[] };
  /** Match on query-string key/value pairs. */
  query?: { key?: string; value: string }[];
  /**
   * The rule's evaluation priority (1–50000, lower first). When omitted, a
   * deterministic priority is derived by hashing the rule's namespaced
   * logical id — stable across deploys and distinct across services. On a
   * live collision the deploy fails with a typed
   * `ListenerRulePriorityInUse` error naming the priority; set an explicit
   * `priority` to resolve it (the engine never probes for free slots).
   */
  priority?: number;
}

/** Object form of the {@link ServiceLoadBalancerConfig.domain} prop. */
export interface ServiceDomainConfig {
  /** Domain name pointed at the owned load balancer, e.g. `api.example.com`. */
  name: string;
  /**
   * Additional domain names aliased to the load balancer. Each alias gets
   * its own Route 53 alias records and (when the certificate is composed) a
   * subject alternative name on the ACM certificate.
   */
  aliases?: string[];
  /**
   * ARN of an existing ACM certificate (in the service's region) for the
   * HTTPS/TLS listener. When omitted, a DNS-validated `AWS.ACM.Certificate`
   * is composed in the matching Route 53 hosted zone (or through
   * {@link dns}).
   */
  cert?: string;
  /**
   * DNS host for the certificate validation and alias records (see
   * [DNS Adapters](/infrastructure-as-code/dns-adapters)). Omitted: Route
   * 53 (a matching public hosted zone must exist; alias `A` + `AAAA`
   * records). Pass `Cloudflare.DNS.Adapter()` or `Hetzner.DNS.Adapter()`
   * for a domain whose DNS lives there — each name gets a `CNAME` to the
   * load balancer and the certificate is validated through that host.
   */
  dns?: DnsConfig;
}

/**
 * Per-target-group health-check overrides, keyed by the target's
 * `"{port}/{protocol}"` spec (see {@link ServiceLoadBalancerConfig.health}).
 */
export interface ServiceTargetHealthCheck {
  /** Health-check path (HTTP/HTTPS checks). */
  path?: string;
  /** Approximate interval between checks, e.g. `"15 seconds"`. */
  interval?: Duration.Input;
  /** Time to wait for a response, e.g. `"5 seconds"`. */
  timeout?: Duration.Input;
  /** Consecutive successes before a target is healthy. */
  healthyThreshold?: number;
  /** Consecutive failures before a target is unhealthy. */
  unhealthyThreshold?: number;
  /** HTTP codes counted as healthy, e.g. `"200-299"`. */
  successCodes?: string;
}

/** Object form of the {@link ServicePropsBase.loadBalancer} prop. */
export interface ServiceLoadBalancerConfig {
  /**
   * Default (shared) listener for rules that omit `listen`. Referencing an
   * `ELBv2.Listener` means the service only creates target groups and
   * listener rules — the ALB and listener belong to whoever composed them.
   */
  listener?: Listener;
  /** Routing rules. Defaults to a single catch-all (`path: "/*"`) rule when a `listener` is referenced. */
  rules?: ServiceLoadBalancerRule[];
  /**
   * Owned-only: whether the composed ALB is internet-facing (`true`, the
   * default) or internal (`false`). A typed error on shared listeners.
   */
  public?: boolean;
  /**
   * Owned-only: point a custom domain at the composed load balancer.
   *
   * By default a matching Route 53 hosted zone must exist (looked up by
   * walking the domain's labels) and alias A + AAAA records are composed for
   * the domain and every alias; set {@link ServiceDomainConfig.dns} to
   * `Cloudflare.DNS.Adapter()` for a domain whose DNS lives in Cloudflare.
   * Unless {@link ServiceDomainConfig.cert} supplies an existing certificate
   * ARN, a DNS-validated `AWS.ACM.Certificate` is composed in the service's
   * region and attached to the HTTPS listener (the default listener becomes
   * `443/https`). The service `url` prefers
   * the domain.
   */
  domain?: string | ServiceDomainConfig;
  /**
   * Per-target-group health-check overrides, keyed by the target's
   * `"{port}/{protocol}"` spec — the rule's `forward` spec, or
   * `"{containerPort}/http"` (`/tcp` for network load balancers) for the
   * default target group. Overrides the fast-converge defaults
   * (10s interval / 2 healthy / 2 unhealthy). A key matching no target
   * group is a typed error ({@link ServiceHealthTargetNotFound}).
   */
  health?: Record<string, ServiceTargetHealthCheck>;
}

/**
 * @internal Resolved managed-ingress wiring computed by the Service factory's
 * composition step — never set by hand. Carries the composed (or shared)
 * ELBv2 child-resource outputs into the core service provider.
 */
export interface ServiceManagedIngress {
  /** Whether the service owns its ALB or shares a foreign listener. */
  kind: "owned" | "shared";
  /** ARN of the (owned or shared) load balancer, for URL derivation. */
  loadBalancerArn?: string;
  /** ARN of the primary listener. */
  listenerArn?: string;
  /** Port of the primary listener. */
  listenerPort?: number;
  /** Protocol of the primary listener (`HTTP` / `HTTPS`). */
  listenerProtocol?: string;
  /** Id of the composed managed security group, when no `securityGroups` were supplied. */
  securityGroupId?: string;
  /** Custom domain pointed at the owned load balancer (URL derivation prefers it). */
  domain?: string;
  /** Target groups to wire into the ECS service definition. */
  targets: {
    /** ARN of the composed target group. */
    targetGroupArn: string;
    /** Container port receiving traffic. Defaults to the main container's port. */
    containerPort?: number;
    /** Container name receiving traffic. Defaults to the main container. */
    container?: string;
  }[];
}

/** Owned `"80/http"` listen strings mixed with shared `ELBv2.Listener` references in one service. */
export class MixedListenerOwnership extends Data.TaggedError("MixedListenerOwnership")<{
  readonly serviceId: string;
  readonly message: string;
}> {}

/** A rule declared both `forward` and `redirect` (mutually exclusive). */
export class ServiceRuleActionConflict extends Data.TaggedError("ServiceRuleActionConflict")<{
  readonly serviceId: string;
  readonly ruleIndex: number;
  readonly message: string;
}> {}

/** A `listen`/`forward`/`redirect` spec used a protocol outside the supported set. */
export class UnsupportedListenerProtocol extends Data.TaggedError("UnsupportedListenerProtocol")<{
  readonly serviceId: string;
  readonly spec: string;
  readonly message: string;
}> {}

/** An owned `https` listener was requested without a `certificateArn`. */
export class MissingListenerCertificate extends Data.TaggedError("MissingListenerCertificate")<{
  readonly serviceId: string;
  readonly spec: string;
  readonly message: string;
}> {}

/** An owned-only option (e.g. `public`) was set while sharing a foreign listener. */
export class OwnedOnlyLoadBalancerOption extends Data.TaggedError("OwnedOnlyLoadBalancerOption")<{
  readonly serviceId: string;
  readonly option: string;
  readonly message: string;
}> {}

/** A rule has neither its own `listen` nor a config-level default `listener`. */
export class MissingRuleListener extends Data.TaggedError("MissingRuleListener")<{
  readonly serviceId: string;
  readonly ruleIndex: number;
  readonly message: string;
}> {}

/** Application (`http`/`https`) and network (`tcp`/`udp`/`tls`/`tcp_udp`) protocols mixed in one service. */
export class MixedLoadBalancerProtocols extends Data.TaggedError("MixedLoadBalancerProtocols")<{
  readonly serviceId: string;
  readonly message: string;
}> {}

/** A network (NLB) rule used a feature NLB listeners don't support (conditions, `redirect`, shared listeners, or a missing/duplicate `listen`). */
export class NetworkListenerRuleUnsupported extends Data.TaggedError(
  "NetworkListenerRuleUnsupported",
)<{
  readonly serviceId: string;
  readonly ruleIndex: number;
  readonly message: string;
}> {}

/** No public Route 53 hosted zone matches the requested `domain`. */
export class ServiceHostedZoneNotFound extends Data.TaggedError("ServiceHostedZoneNotFound")<{
  readonly serviceId: string;
  readonly domainName: string;
  readonly message: string;
}> {}

/** A `health` key matched none of the service's composed target groups. */
export class ServiceHealthTargetNotFound extends Data.TaggedError("ServiceHealthTargetNotFound")<{
  readonly serviceId: string;
  readonly key: string;
  readonly message: string;
}> {}

/** `scaling.requestCount` needs a managed (owned or shared) target group to track. */
export class RequestCountScalingRequiresLoadBalancer extends Data.TaggedError(
  "RequestCountScalingRequiresLoadBalancer",
)<{
  readonly serviceId: string;
  readonly message: string;
}> {}

/** An ECS service did not converge to the requested deployment before timeout. */
export class ServiceDidNotStabilize extends Data.TaggedError("ServiceDidNotStabilize")<{
  readonly clusterArn: string;
  readonly serviceName: string;
  readonly expectedTaskDefinitionArn: string | undefined;
  readonly status: string | undefined;
  readonly desiredCount: number | undefined;
  readonly runningCount: number | undefined;
  readonly pendingCount: number | undefined;
  readonly deploymentCount: number;
  readonly unhealthyTargetCount: number;
  readonly message: string;
}> {}

/**
 * Derive a deterministic listener-rule priority (1–50000) from the rule's
 * namespaced logical id (FNV-1a 32-bit). Stable across deploys for the same
 * id and distinct for distinct ids; on a live `PriorityInUse` collision the
 * deploy fails with a typed error rather than probing for a free slot.
 */
export const deriveRulePriority = (namespacedLogicalId: string): number => {
  let hash = 0x811c9dc5;
  for (let i = 0; i < namespacedLogicalId.length; i++) {
    hash ^= namespacedLogicalId.charCodeAt(i);
    hash = Math.imul(hash, 0x01000193) >>> 0;
  }
  return (hash % 50000) + 1;
};

/**
 * Autoscaling configuration for the service's desired count. Composes an
 * `AWS.ApplicationAutoScaling.ScalableTarget` plus one target-tracking
 * `ScalingPolicy` per declared metric under the service's namespace.
 */
export interface ServiceScalingConfig {
  /**
   * Minimum number of running tasks Application Auto Scaling may scale in to.
   * @default 1
   */
  min?: number;
  /**
   * Maximum number of running tasks Application Auto Scaling may scale out to.
   * @default `min`
   */
  max?: number;
  /** Target average CPU utilization (percent) to track. */
  cpuUtilization?: number;
  /** Target average memory utilization (percent) to track. */
  memoryUtilization?: number;
  /**
   * Target `ALBRequestCountPerTarget` to track. Requires a managed load
   * balancer target group ({@link ServicePropsBase.loadBalancer}) — a typed
   * error ({@link RequestCountScalingRequiresLoadBalancer}) otherwise.
   */
  requestCount?: number;
  /** Cooldown after a scale-in activity, e.g. `"5 minutes"`. */
  scaleInCooldown?: Duration.Input;
  /** Cooldown after a scale-out activity, e.g. `"1 minute"`. */
  scaleOutCooldown?: Duration.Input;
}

/**
 * Fargate capacity split for the service. `"spot"` runs everything on
 * `FARGATE_SPOT`; the object form weights on-demand (`fargate`) against
 * `spot` capacity. Normalized into
 * {@link ServicePropsBase.capacityProviderStrategy}. The cluster must have
 * the `FARGATE` / `FARGATE_SPOT` capacity providers associated (see
 * `AWS.ECS.Cluster`'s `capacityProviders` prop).
 */
export type ServiceCapacityConfig =
  | "spot"
  | {
      /** On-demand Fargate share. */
      fargate?: {
        /** Baseline task count placed on this provider before weights apply. */
        base?: number;
        /** Relative share of tasks placed on this provider. */
        weight: number;
      };
      /** Fargate Spot share. */
      spot?: {
        /** Baseline task count placed on this provider before weights apply. */
        base?: number;
        /** Relative share of tasks placed on this provider. */
        weight: number;
      };
    };

/**
 * Cloud Map service-discovery registration. Composes an
 * `AWS.CloudMap.Service` in the given namespace and wires it into the ECS
 * service's `serviceRegistries`.
 */
export interface ServiceRegistryConfig {
  /**
   * The Cloud Map namespace to register in — an
   * `AWS.CloudMap.PrivateDnsNamespace` or `HttpNamespace` (anything with a
   * `namespaceId`).
   */
  namespace: { namespaceId: string };
  /**
   * SRV port to publish. When set, the composed Cloud Map service uses SRV
   * records; otherwise A records (DNS namespaces) or API-only discovery
   * (HTTP namespaces).
   */
  port?: number;
}

/** Container-level health check (Docker `HEALTHCHECK` shape) for the primary container. */
export interface ServiceContainerHealthCheck {
  /**
   * The check command, e.g.
   * `["CMD-SHELL", "curl -f http://localhost/ || exit 1"]`.
   */
  command: string[];
  /** Seconds-granularity period between checks, e.g. `"30 seconds"`. */
  interval?: Duration.Input;
  /** Time to wait for a check before counting it failed, e.g. `"5 seconds"`. */
  timeout?: Duration.Input;
  /** Consecutive failures before the container is unhealthy. */
  retries?: number;
  /** Grace period before failed checks count, e.g. `"10 seconds"`. */
  startPeriod?: Duration.Input;
}

/** Retention policy for the service's auto-created CloudWatch log group. */
export type ServiceLoggingConfig = LogRetentionConfig;

/** EFS volume sugar for {@link ImageOwningServicePropsBase.volumes}. */
export interface ServiceEfsVolume {
  /**
   * The EFS file system to mount — an `AWS.EFS.FileSystem` (anything with a
   * `fileSystemId`), or `{ fileSystem, accessPoint }` to mount through an
   * `AWS.EFS.AccessPoint`. Transit encryption is always enabled.
   */
  efs:
    | { fileSystemId: string }
    | {
        /** The EFS file system. */
        fileSystem: { fileSystemId: string };
        /** Optional access point to mount through. */
        accessPoint?: { accessPointId: string };
      };
  /** Container path to mount the file system at, e.g. `"/mnt/data"`. */
  path: string;
}

export interface ServicePropsBase extends PlatformProps {
  /**
   * ECS cluster that will own the service.
   */
  cluster: ClusterArn | { clusterArn: ClusterArn };

  /**
   * Name of the ECS service.
   * If omitted, a unique name will be generated.
   *
   * Changing this replaces the service (delete-first).
   */
  serviceName?: string;

  /**
   * Desired number of running tasks. Updated in place.
   * @default 1
   */
  desiredCount?: number;

  /**
   * VPC that hosts the service networking and optional public ingress.
   * When omitted (together with {@link subnets}), the account's default VPC
   * is used.
   */
  vpcId?: string;

  /**
   * Subnets used by the service's awsvpc network configuration. Updated in
   * place via `updateService`. When omitted (together with {@link vpcId}),
   * the default VPC's per-AZ default subnets are used.
   */
  subnets?: string[];

  /**
   * Security groups attached to the service ENIs and any Alchemy-managed
   * load balancer. When omitted and {@link loadBalancer} is set, Alchemy
   * provisions (and owns) a security group that admits the listener port
   * from anywhere and the container port from within the group.
   */
  securityGroups?: string[];

  /**
   * Whether the service ENIs should receive public IPs.
   * @default false — but `true` when networking defaulted to the default
   * VPC (public subnets need a public IP to pull images without a NAT).
   */
  assignPublicIp?: boolean;

  /**
   * Launch type for the service. Mutually exclusive with
   * {@link capacityProviderStrategy}. Switching between launch type and
   * capacity-provider strategy replaces the service.
   * @default "FARGATE"
   */
  launchType?: ecs.LaunchType;

  /**
   * Capacity provider strategy for the service (e.g. `FARGATE`/`FARGATE_SPOT`
   * weights, or a custom ASG-backed provider). Mutually exclusive with
   * {@link launchType}. Switching to/from a launch type replaces the service;
   * weight/base changes apply in place.
   */
  capacityProviderStrategy?: ecs.CapacityProviderStrategyItem[];

  /**
   * Fargate capacity sugar: `"spot"` runs every task on `FARGATE_SPOT`, or
   * weight on-demand against spot capacity. Normalized into
   * {@link capacityProviderStrategy} (which it must not be combined with).
   * The cluster needs the Fargate capacity providers associated.
   */
  capacity?: ServiceCapacityConfig;

  /**
   * Autoscale the service's desired count: composes an Application Auto
   * Scaling scalable target (bounded by `min`/`max`) plus a target-tracking
   * policy per declared metric (`cpuUtilization`, `memoryUtilization`,
   * `requestCount`). While set, deploys stop pinning `desiredCount` so the
   * autoscaler's decisions survive redeploys.
   */
  scaling?: ServiceScalingConfig;

  /**
   * Register the service in an AWS Cloud Map namespace: composes an
   * `AWS.CloudMap.Service` and wires it into the ECS service's
   * {@link serviceRegistries}.
   */
  serviceRegistry?: ServiceRegistryConfig;

  /**
   * Load balancer target groups to wire to the service. **User-supplied** —
   * Alchemy does NOT create these. Each entry references an existing ELBv2
   * target group (or CLB) plus the container/port that receives traffic.
   * Updated in place for rolling deployments.
   *
   * For an Alchemy-managed public ALB instead, set {@link loadBalancer} to
   * `true`.
   */
  loadBalancers?: ecs.LoadBalancer[];

  /**
   * Cloud Map service registries (service discovery) to associate with the
   * service.
   */
  serviceRegistries?: ecs.ServiceRegistry[];

  /**
   * Managed load balancing for the service, composed as REAL
   * `AWS.ELBv2.LoadBalancer` / `Listener` / `TargetGroup` / `ListenerRule`
   * child resources under the service's namespace:
   *
   * - `true` — the service OWNS a public ALB with a single HTTP listener
   *   forwarding to the container port. The `url` attribute is populated
   *   from the ALB's DNS name.
   * - an `ELBv2.Listener` reference — the listener (and its ALB) are SHARED:
   *   the service only creates a target group and a catch-all
   *   (`path: "/*"`) listener rule on that listener. Destroying the service
   *   removes its rules and target groups; the shared listener/ALB are never
   *   touched.
   * - an object — `listener` (default shared listener) + `rules` (path/host/
   *   header/query routing, `forward`/`redirect` actions) + `public`
   *   (owned-only; `false` composes an internal ALB). Rules with
   *   `"80/http"`-style `listen` strings make the service own the ALB and
   *   those listeners; `ELBv2.Listener` references share existing ones.
   *   Mixing both in one service is a typed error.
   *
   * Migration note: services deployed before composed ingress recorded their
   * inline-created ALB/TG/listener/security group in the service's own
   * attributes. The first deploy under the composed shape performs a
   * breaking redeploy — new composed resources are created and the legacy
   * inline infrastructure is reaped (deleted) so nothing is stranded.
   * @default false
   */
  loadBalancer?: boolean | Listener | ServiceLoadBalancerConfig;

  /**
   * Legacy alias for {@link loadBalancer}.
   * @deprecated use `loadBalancer: true`
   */
  public?: boolean;

  /**
   * @internal Resolved managed-ingress wiring computed by the Service
   * factory's composition step. Never set by hand.
   */
  ingress?: ServiceManagedIngress;

  /**
   * Listener port for generated public ingress.
   * @default 80 when `certificateArn` is omitted, otherwise 443
   */
  listenerPort?: number;

  /**
   * ACM certificate ARN for HTTPS public ingress.
   * When provided, the generated listener uses HTTPS.
   */
  certificateArn?: string;

  /**
   * Target group health check path for public HTTP services.
   * @default "/"
   */
  healthCheckPath?: string;

  /**
   * Fargate platform version for the service. Updated in place.
   */
  platformVersion?: string;

  /**
   * Raw ECS deployment configuration (rolling update percentages, circuit
   * breaker, deployment strategy, alarms). Updated in place.
   */
  deploymentConfiguration?: ecs.DeploymentConfiguration;

  /**
   * Maximum time to wait for an ECS deployment, old-task drain, and target
   * health to converge before failing the resource operation. The provider
   * hard-caps this at 30 minutes so polling always remains bounded.
   * @default "10 minutes"
   */
  deploymentStabilizationTimeout?: Duration.Input;

  /**
   * Deployment controller (`ECS`, `CODE_DEPLOY`, `EXTERNAL`). The controller
   * type is immutable — changing it replaces the service.
   */
  deploymentController?: ecs.DeploymentController;

  /**
   * Placement constraints (`distinctInstance` / `memberOf`). Updated in place.
   */
  placementConstraints?: ecs.PlacementConstraint[];

  /**
   * Placement strategy (`random` / `spread` / `binpack`). Updated in place.
   */
  placementStrategy?: ecs.PlacementStrategy[];

  /**
   * Scheduling strategy. `REPLICA` runs and maintains `desiredCount` copies;
   * `DAEMON` runs one task per eligible instance. Immutable — changing it
   * replaces the service.
   * @default "REPLICA"
   */
  schedulingStrategy?: ecs.SchedulingStrategy;

  /**
   * Whether to enable ECS Exec on the service tasks. Updated in place.
   * @default false
   */
  enableExecuteCommand?: boolean;

  /**
   * Whether to enable ECS managed tags. Immutable post-create.
   * @default true
   */
  enableECSManagedTags?: boolean;

  /**
   * How to propagate tags to tasks (`TASK_DEFINITION`, `SERVICE`, `NONE`).
   * Updated in place.
   */
  propagateTags?: ecs.PropagateTags;

  /**
   * Availability zone rebalancing behavior. Updated in place.
   */
  availabilityZoneRebalancing?: ecs.AvailabilityZoneRebalancing;

  /**
   * ECS Service Connect configuration. Updated in place.
   */
  serviceConnectConfiguration?: ecs.ServiceConnectConfiguration;

  /**
   * Service-managed volume configurations. Updated in place.
   */
  volumeConfigurations?: ecs.ServiceVolumeConfiguration[];

  /**
   * IAM role for the ELB integration (only for non-awsvpc / CLB services).
   * Immutable — changing it replaces the service.
   */
  role?: string;

  /**
   * Grace period before ECS starts evaluating target health checks, e.g.
   * `"30 seconds"` or `Duration.seconds(30)`. Rounded to whole seconds on
   * the wire. Updated in place.
   */
  healthCheckGracePeriod?: Duration.Input;

  /**
   * User-defined tags to apply to the ECS service and generated ingress
   * resources. Reconciled in place against observed service tags.
   */
  tags?: Record<string, string>;
}

/**
 * Deploy an existing `AWS.ECS.Task`'s definition as a service (shared
 * image/roles/config; the Service adds `desiredCount` / load balancing /
 * deployment configuration).
 */
export interface TaskReferenceServiceProps extends ServicePropsBase {
  /**
   * Bundled ECS task to run for each service replica: the runtime-facing
   * subset of `AWS.ECS.Task` attributes the service needs to deploy and
   * wire load balancer traffic (a full `Task` satisfies it structurally).
   */
  task: {
    /**
     * Registered task definition ARN to deploy.
     */
    taskDefinitionArn: string;
    /**
     * Container name inside the task definition that should receive traffic.
     */
    containerName: string;
    /**
     * Container port that the service should expose and forward traffic to.
     */
    port: number;
  };
}

/**
 * Image-owning base: the Service synthesizes its own task definition
 * (roles, log group, ECR repository, image) from the shared
 * {@link TaskDefinitionConfig} surface.
 */
export interface ImageOwningServicePropsBase
  extends ServicePropsBase, Omit<TaskDefinitionConfig, "placementConstraints" | "volumes"> {
  /**
   * Task definition placement constraints (`memberOf` expressions) for the
   * synthesized task definition. (`placementConstraints` on the service
   * itself remains the service-level ECS placement constraint list.)
   */
  taskPlacementConstraints?: ecs.TaskDefinitionPlacementConstraint[];

  /**
   * Secrets injected into the primary container as environment variables:
   * env-var name → SSM Parameter Store parameter ARN or Secrets Manager
   * secret ARN. Wired as container `secrets` (`valueFrom`), with the
   * execution role granted `ssm:GetParameters` /
   * `secretsmanager:GetSecretValue` on exactly the referenced ARNs.
   */
  secrets?: Record<string, string>;

  /**
   * Container-level health check (Docker `HEALTHCHECK`) for the primary
   * container, e.g.
   * `{ command: ["CMD-SHELL", "curl -f http://localhost/ || exit 1"] }`.
   */
  healthCheck?: ServiceContainerHealthCheck;

  /**
   * Task-level data volumes. Accepts raw {@link ecs.Volume} entries
   * (referenced by the container via `mountPoints`) or the EFS sugar
   * `{ efs, path }`, which composes the volume AND mounts it at `path` on
   * the primary container with transit encryption enabled.
   */
  volumes?: (ecs.Volume | ServiceEfsVolume)[];
}

/** Bundle an inline Effect program (`main`) into the service's image. */
export interface BundledServiceProps extends ImageOwningServicePropsBase, BundledImageSource {}
/** Build the user's own Dockerfile into the service's image. */
export interface DockerfileServiceProps
  extends ImageOwningServicePropsBase, DockerfileImageSource {}
/** Run a pre-built registry image, mirrored into ECR. */
export interface ImageServiceProps extends ImageOwningServicePropsBase, RegistryImageSource {}

/**
 * Service props — either reference an existing task definition (`task:`) or
 * own the image via exactly one of `main` / `context` / `image` (the
 * Service then synthesizes its own task definition).
 */
export type ServiceProps =
  | TaskReferenceServiceProps
  | BundledServiceProps
  | DockerfileServiceProps
  | ImageServiceProps;

export interface Service extends Resource<
  "AWS.ECS.Service",
  ServiceProps,
  {
    /**
     * ARN of the ECS service.
     */
    serviceArn: ServiceArn;

    /**
     * Name of the ECS service.
     */
    serviceName: ServiceName;

    /**
     * ARN of the cluster that owns the service.
     */
    clusterArn: ClusterArn;

    /**
     * Task definition revision currently deployed by the service.
     */
    taskDefinitionArn: string;

    /**
     * ECS service status such as `ACTIVE` or `DRAINING`.
     */
    status: string;

    /**
     * URL of the service through its managed ingress. Owned load balancers
     * use the composed ALB's DNS name; shared listeners derive it from the
     * foreign listener's ALB DNS + protocol/port (best-effort — undefined
     * when not derivable).
     */
    url?: string;

    /**
     * ARN of the load balancer serving the service's managed ingress (the
     * composed ALB when owned; the shared listener's ALB otherwise).
     */
    loadBalancerArn?: string;

    /**
     * ARN of the first managed target group, when `loadBalancer` is set.
     */
    targetGroupArn?: string;

    /**
     * ARN of the primary listener, when `loadBalancer` is set.
     */
    listenerArn?: string;

    /**
     * Id of the Alchemy-managed security group composed for managed ingress
     * (only when `loadBalancer` is set and no `securityGroups` supplied).
     */
    securityGroupId?: string;

    /**
     * @internal Marks attrs written by the composed-ingress shape ("owned" |
     * "shared"). Absent on legacy state rows whose ALB/TG/listener were
     * created inline by the provider — the marker gates the migration reap
     * and the legacy delete path.
     */
    ingressKind?: "owned" | "shared";

    /**
     * Desired count, networking, load balancers, service registries, the
     * declared deployment/placement/execute-command settings and the tags,
     * as observed. Lets `alchemy drift` detect out-of-band changes.
     */
    configuration?: Record<string, unknown>;

    /** Family of the synthesized task definition (image-owning form only). */
    taskFamily?: string;
    /** Name of the primary container (image-owning form only). */
    containerName?: string;
    /** Container port receiving traffic (image-owning form only). */
    port?: number;
    /** Image URI the synthesized task definition runs. */
    imageUri?: string;
    /** ECR repository name holding the service's image. */
    repositoryName?: string;
    /** ECR repository URI holding the service's image. */
    repositoryUri?: string;
    /** ARN of the synthesized task role. */
    taskRoleArn?: string;
    /** Name of the synthesized task role. */
    taskRoleName?: string;
    /** ARN of the synthesized execution role. */
    executionRoleArn?: string;
    /** Name of the synthesized execution role. */
    executionRoleName?: string;
    /** CloudWatch log group of the synthesized task definition. */
    logGroupName?: string;
    /** ARN of the CloudWatch log group. */
    logGroupArn?: string;
    /** Content hash of the service's container image. */
    code?: {
      /** Content hash of the service's container image. */
      hash: string;
    };
  },
  TaskBindingContract,
  Providers
> {}

export type ServiceServices = Credentials | Region | ServerHost | AWSEnvironment;

/**
 * The impl shape for an effectful `Service`: a long-running server returning
 * `{ fetch }` (plus optional RPC methods).
 */
export type ServiceShape = Main<ServiceServices>;

export interface ServiceRuntimeContext extends HostRuntimeContext {
  readonly Type: "AWS.ECS.Service";
}

/**
 * An ECS service: N copies of a container kept alive, optionally behind a
 * load balancer.
 *
 * The service's image comes from one of four sources:
 *
 * - `image` — run a pre-built registry image, mirrored into ECR.
 * - `context` — build your own Dockerfile.
 * - `main` — bundle an inline Effect program (servers return `{ fetch }`).
 * - `task:` — deploy an existing `AWS.ECS.Task`'s definition; the Service
 *   adds `desiredCount` / load balancing / deployment configuration.
 *
 * With any of the first three the Service synthesizes its own task
 * definition (task + execution roles, log group, ECR repository).
 * `loadBalancer: true` wires a public ALB + target group + listener and
 * populates the `url` attribute. When `vpcId`/`subnets` are omitted the
 * account's default VPC (and its per-AZ subnets) is used.
 *
 * Most configuration is updated **in place** via `updateService`
 * (desiredCount, task definition, network, deployment config, placement,
 * exec, load balancers, tags). Only truly-immutable aspects — `serviceName`,
 * `cluster`, launchType↔capacityProviderStrategy switch, `deploymentController`
 * type, `schedulingStrategy`, `enableECSManagedTags`, `role` — replace the
 * service.
 * ### Creating Services
 * **Example:** Remote Image Behind a Load Balancer
 * ```typescript
 * const nginx = yield* Service("Edge", {
 *   cluster,
 *   image: "public.ecr.aws/nginx/nginx:1.27",
 *   port: 80,
 *   desiredCount: 2,
 *   loadBalancer: true,   // ALB + target group + listener wiring
 * });
 * nginx.url; // http://<alb-dns-name>
 * ```
 *
 * **Example:** Run an Existing Task's Definition
 * ```typescript
 * const api = yield* Service("Api", {
 *   cluster,
 *   task: apiTask,        // shared image/roles/config; Service adds
 *   desiredCount: 2,      // desiredCount / LB / deployment config
 *   loadBalancer: true,
 * });
 * ```
 *
 * **Example:** Inline Effect Server
 * ```typescript
 * const api = yield* Service(
 *   "Api",
 *   { cluster, main: import.meta.url, port: 3000, desiredCount: 2, cpu: 256, memory: 512 },
 *   Effect.gen(function* () {
 *     const putItem = yield* AWS.DynamoDB.PutItem(table);
 *     return {
 *       fetch: Effect.gen(function* () {
 *         return yield* HttpServerResponse.json({ ok: true });
 *       }),
 *     };
 *   }).pipe(Effect.provide(AWS.DynamoDB.PutItemHttp)),
 * );
 * ```
 *
 * ### Bundling & Tree-shaking
 * `main` is bundled with rolldown at deploy time. Unused code is
 * tree-shaken. `effect`, alchemy, and `@distilled.cloud` are marked
 * pure so unused parts prune more aggressively. Your app is not
 * marked pure.
 *
 * **Example:** Mark additional packages as pure
 * Only list packages with no top-level side effects.
 * ```typescript
 * {
 *   main: import.meta.url,
 *   build: {
 *     pure: { packages: ["my-lib", "@my-scope/*"] },
 *   },
 * }
 * ```
 *
 * **Example:** Turn it off
 * ```typescript
 * {
 *   main: import.meta.url,
 *   build: { pure: false },
 * }
 * ```
 *
 * ### Shared Load Balancers
 * **Example:** Two Services Sharing One Listener
 * ```typescript
 * // The ALB + listener are stack-level resources owned by neither service.
 * const lb = yield* AWS.ELBv2.LoadBalancer("Alb", {
 *   subnets: [subnetA.subnetId, subnetB.subnetId],
 *   securityGroups: [sg.groupId],
 * });
 * const listener = yield* AWS.ELBv2.Listener("Http", {
 *   loadBalancerArn: lb.loadBalancerArn,
 *   port: 80,
 *   defaultActions: [
 *     { type: "fixedResponse", statusCode: "404", messageBody: "no route" },
 *   ],
 * });
 *
 * // Each service composes only its own TargetGroup + ListenerRule on the
 * // shared listener. Destroying one service removes its rule + target
 * // group; the ALB, listener, and the other service are untouched.
 * const api = yield* Service("Api", {
 *   cluster,
 *   image: "my-org/api:latest",
 *   port: 3000,
 *   loadBalancer: { listener, rules: [{ path: "/api/*" }] },
 * });
 * const web = yield* Service("Web", {
 *   cluster,
 *   image: "my-org/web:latest",
 *   port: 8080,
 *   loadBalancer: { listener, rules: [{ path: "/*" }] },
 * });
 * ```
 *
 * **Example:** Catch-All on a Shared Listener
 * ```typescript
 * // A bare listener reference adds a single `path: "/*"` rule.
 * const svc = yield* Service("Svc", {
 *   cluster,
 *   image: "my-org/web:latest",
 *   port: 8080,
 *   loadBalancer: listener,
 * });
 * ```
 *
 * **Example:** Owned ALB with Routing Rules and an HTTP → HTTPS Redirect
 * ```typescript
 * // `"80/http"`-style `listen` strings mean the service OWNS the ALB and
 * // these listeners (mixing them with shared listener references is a
 * // typed error).
 * const svc = yield* Service("Svc", {
 *   cluster,
 *   image: "my-org/web:latest",
 *   port: 8080,
 *   certificateArn,
 *   loadBalancer: {
 *     rules: [
 *       { listen: "80/http", redirect: "443/https" },
 *       { listen: "443/https", forward: "8080/http" },
 *     ],
 *   },
 * });
 * ```
 *
 * ### Custom Domains
 * **Example:** Domain with a Composed Certificate
 * ```typescript
 * // Looks up the matching Route 53 hosted zone, composes a DNS-validated
 * // ACM certificate in the service's region, wires it to the HTTPS
 * // listener, and creates alias A/AAAA records. `url` becomes
 * // https://api.example.com.
 * const svc = yield* Service("Api", {
 *   cluster,
 *   image: "my-org/api:latest",
 *   port: 3000,
 *   loadBalancer: { domain: "api.example.com" },
 * });
 * ```
 *
 * **Example:** Domain with an Existing Certificate
 * ```typescript
 * const svc = yield* Service("Api", {
 *   cluster,
 *   image: "my-org/api:latest",
 *   port: 3000,
 *   loadBalancer: {
 *     domain: { name: "api.example.com", aliases: ["www.api.example.com"], cert: certificateArn },
 *   },
 * });
 * ```
 *
 * **Example:** Domain on Cloudflare DNS
 * ```typescript
 * // The certificate is validated through the Cloudflare zone and each
 * // name gets a CNAME to the load balancer. Requires
 * // `Cloudflare.providers()` in the stack.
 * const svc = yield* Service("Api", {
 *   cluster,
 *   image: "my-org/api:latest",
 *   port: 3000,
 *   loadBalancer: {
 *     domain: { name: "api.example.com", dns: Cloudflare.DNS.Adapter() },
 *   },
 * });
 * ```
 *
 * ### Network Load Balancers
 * **Example:** TCP Service Behind an NLB
 * ```typescript
 * // tcp/udp/tls/tcp_udp listen protocols compose a Network Load Balancer;
 * // each rule's action becomes its listener's default forward (NLB
 * // listeners route by port alone).
 * const svc = yield* Service("Tcp", {
 *   cluster,
 *   image: "my-org/tcp-echo:latest",
 *   port: 9000,
 *   loadBalancer: { rules: [{ listen: "80/tcp" }] },
 * });
 * ```
 *
 * ### Health Checks
 * **Example:** Per-Target-Group Health Overrides
 * ```typescript
 * const svc = yield* Service("Api", {
 *   cluster,
 *   image: "my-org/api:latest",
 *   port: 3000,
 *   loadBalancer: {
 *     rules: [{ listen: "80/http" }],
 *     health: {
 *       "3000/http": {
 *         path: "/healthz",
 *         interval: "15 seconds",
 *         healthyThreshold: 3,
 *         successCodes: "200-299",
 *       },
 *     },
 *   },
 * });
 * ```
 *
 * **Example:** Container Health Check
 * ```typescript
 * const svc = yield* Service("Api", {
 *   cluster,
 *   image: "my-org/api:latest",
 *   port: 3000,
 *   healthCheck: {
 *     command: ["CMD-SHELL", "curl -f http://localhost:3000/ || exit 1"],
 *     interval: "30 seconds",
 *     retries: 3,
 *   },
 * });
 * ```
 *
 * ### Autoscaling
 * **Example:** Target-Tracking Autoscaling
 * ```typescript
 * // Composes a ScalableTarget (min/max) plus one target-tracking policy
 * // per metric. Redeploys stop pinning desiredCount while scaling is set.
 * const svc = yield* Service("Api", {
 *   cluster,
 *   image: "my-org/api:latest",
 *   port: 3000,
 *   loadBalancer: true,
 *   scaling: {
 *     min: 1,
 *     max: 4,
 *     cpuUtilization: 70,
 *     requestCount: 200,
 *     scaleInCooldown: "5 minutes",
 *   },
 * });
 * ```
 *
 * ### Secrets & Logging
 * **Example:** Inject SSM / Secrets Manager Secrets
 * ```typescript
 * // Values are ARNs; the container gets them as env vars via `valueFrom`
 * // and the execution role is granted read on exactly these ARNs.
 * const svc = yield* Service("Api", {
 *   cluster,
 *   image: "my-org/api:latest",
 *   port: 3000,
 *   secrets: {
 *     DB_PASSWORD: dbPasswordSecret.secretArn,
 *     API_KEY: apiKeyParameter.parameterArn,
 *   },
 *   logging: { retention: "2 weeks" },
 * });
 * ```
 *
 * ### Service Discovery
 * **Example:** Register in a Cloud Map Namespace
 * ```typescript
 * const namespace = yield* AWS.CloudMap.PrivateDnsNamespace("AppNs", {
 *   name: "internal.example.com",
 *   vpc: vpc.vpcId,
 * });
 * const svc = yield* Service("Api", {
 *   cluster,
 *   image: "my-org/api:latest",
 *   port: 3000,
 *   serviceRegistry: { namespace },
 * });
 * ```
 *
 * ### Volumes
 * **Example:** Mount an EFS File System
 * ```typescript
 * const svc = yield* Service("Api", {
 *   cluster,
 *   image: "my-org/api:latest",
 *   port: 3000,
 *   volumes: [{ efs: fileSystem, path: "/mnt/data" }],
 * });
 * ```
 *
 * ### Capacity
 * **Example:** Fargate Spot
 * ```typescript
 * // The cluster must have the Fargate capacity providers associated:
 * // Cluster("C", { capacityProviders: ["FARGATE", "FARGATE_SPOT"] }).
 * const svc = yield* Service("Worker", {
 *   cluster,
 *   image: "my-org/worker:latest",
 *   capacity: { fargate: { weight: 1, base: 1 }, spot: { weight: 4 } },
 * });
 * ```
 *
 * ### Load Balancing
 * **Example:** Manual (User-Supplied) Target Group
 * ```typescript
 * const service = yield* Service("ApiService", {
 *   cluster,
 *   task: apiTask,
 *   vpcId: vpc.vpcId,
 *   subnets: [subnet1.subnetId, subnet2.subnetId],
 *   loadBalancers: [
 *     {
 *       targetGroupArn,
 *       containerName: apiTask.containerName,
 *       containerPort: apiTask.port,
 *     },
 *   ],
 * });
 * ```
 *
 * ### Capacity & Placement
 * **Example:** FARGATE_SPOT Capacity Provider Strategy
 * ```typescript
 * const service = yield* Service("WorkerService", {
 *   cluster,
 *   task: workerTask,
 *   vpcId: vpc.vpcId,
 *   subnets: [subnet.subnetId],
 *   capacityProviderStrategy: [
 *     { capacityProvider: "FARGATE_SPOT", weight: 4 },
 *     { capacityProvider: "FARGATE", weight: 1, base: 1 },
 *   ],
 *   placementStrategy: [{ type: "spread", field: "attribute:ecs.availability-zone" }],
 * });
 * ```
 *
 * ### Deployment
 * **Example:** Rolling Update with Circuit Breaker
 * ```typescript
 * const service = yield* Service("ApiService", {
 *   cluster,
 *   task: apiTask,
 *   vpcId: vpc.vpcId,
 *   subnets: [subnet1.subnetId, subnet2.subnetId],
 *   desiredCount: 3,
 *   enableExecuteCommand: true,
 *   deploymentConfiguration: {
 *     minimumHealthyPercent: 100,
 *     maximumPercent: 200,
 *     deploymentCircuitBreaker: { enable: true, rollback: true },
 *   },
 *   healthCheckGracePeriod: "30 seconds",
 * });
 * ```
 *
 * @resource
 */
export const Service: Platform<Service, ServiceServices, ServiceShape, ServiceRuntimeContext> =
  Platform("AWS.ECS.Service", {
    createRuntimeContext: createContainerRuntimeContext("AWS.ECS.Service") as (
      id: string,
    ) => ServiceRuntimeContext,
    // Compose the managed load balancer (owned ALB/listeners or shared-listener
    // rules + target groups) as REAL namespaced child resources before the core
    // service resource is declared.
    transformProps: (id, props) => transformServiceProps(id, props),
    // Autoscaling references the service's own Output attributes (cluster/name/
    // target-group ARNs), so it composes AFTER the resource exists.
    onCreate: (resource, props) =>
      // oxlint-disable-next-line effecttsgo/unsafe-effect-type-assertion -- Platform onCreate hook type is Effect<void, never, any>; failures still propagate at runtime
      composeServiceScaling(
        resource as Service,
        props as ServiceProps,
        // Typed failures (e.g. RequestCountScalingRequiresLoadBalancer)
        // surface through the deploy like any resource-construction error.
      ) as Effect.Effect<void, never, any>,
  });

/** The BYO task reference, when the props use the `task:` form. */
/**
 * The service settings reconcile converges, as observed on `service`.
 * `read` and `reconcile` share it so a converged service reads unchanged.
 * Settings whose prop is unset are left unchanged by `updateService`, so
 * they are only observed when declared; the desired count is not observed
 * while autoscaling owns it.
 */
const observeServiceConfiguration = (
  service: ecs.Service,
  props: ServiceProps | undefined,
  tags: Record<string, string>,
) => {
  const declared = <V>(key: keyof ServiceProps, value: V) =>
    props?.[key] === undefined ? undefined : value;
  const vpc = service.networkConfiguration?.awsvpcConfiguration;
  return plainJson({
    desiredCount: props?.scaling === undefined ? service.desiredCount : undefined,
    networkConfiguration: vpc && {
      subnets: [...(vpc.subnets ?? [])].sort(),
      securityGroups: [...(vpc.securityGroups ?? [])].sort(),
      assignPublicIp: vpc.assignPublicIp,
    },
    loadBalancers: service.loadBalancers?.length
      ? [...service.loadBalancers].sort((a, b) =>
          JSON.stringify(a).localeCompare(JSON.stringify(b)),
        )
      : undefined,
    serviceRegistries: service.serviceRegistries?.length ? service.serviceRegistries : undefined,
    platformVersion: declared("platformVersion", service.platformVersion),
    deploymentConfiguration: declared("deploymentConfiguration", service.deploymentConfiguration),
    healthCheckGracePeriodSeconds: declared(
      "healthCheckGracePeriod",
      service.healthCheckGracePeriodSeconds,
    ),
    capacityProviderStrategy: declared(
      "capacityProviderStrategy",
      service.capacityProviderStrategy,
    ),
    placementConstraints: declared("placementConstraints", service.placementConstraints),
    placementStrategy: declared("placementStrategy", service.placementStrategy),
    enableExecuteCommand: declared("enableExecuteCommand", service.enableExecuteCommand),
    propagateTags: declared("propagateTags", service.propagateTags),
    availabilityZoneRebalancing: declared(
      "availabilityZoneRebalancing",
      service.availabilityZoneRebalancing,
    ),
    tags,
  });
};

const ecsTagRecord = (tags: ecs.Tag[] | undefined): Record<string, string> =>
  Object.fromEntries(
    (tags ?? []).flatMap((t) =>
      typeof t.key === "string" && typeof t.value === "string" ? [[t.key, t.value]] : [],
    ),
  );

const taskRefOf = (props: ServiceProps | undefined) =>
  props !== undefined && "task" in props ? props.task : undefined;

// ───────────────────────────────────────────────────────────────────────────
// Managed load balancer — composition (the StaticSite pattern)
// ───────────────────────────────────────────────────────────────────────────

const isELBv2Listener = (value: unknown): value is Listener =>
  typeof value === "object" &&
  value !== null &&
  "Type" in value &&
  (value as { Type?: unknown }).Type === "AWS.ELBv2.Listener";

interface ParsedListen {
  port: number;
  protocol: ServiceListenerProtocol;
}

const LISTENER_PROTOCOLS: ReadonlySet<string> = new Set([
  "http",
  "https",
  "tcp",
  "udp",
  "tcp_udp",
  "tls",
]);

const parseListenSpec = (serviceId: string, spec: string, kind: string) =>
  Effect.gen(function* () {
    const [portString, protocol] = spec.split("/");
    const port = Number(portString);
    if (
      !Number.isInteger(port) ||
      port <= 0 ||
      port > 65535 ||
      protocol === undefined ||
      !LISTENER_PROTOCOLS.has(protocol)
    ) {
      return yield* new UnsupportedListenerProtocol({
        serviceId,
        spec,
        message: `AWS.ECS.Service "${serviceId}": unsupported ${kind} spec '${spec}' — expected "<port>/<protocol>" with protocol one of http, https (ALB) or tcp, udp, tcp_udp, tls (NLB)`,
      });
    }
    return { port, protocol } as ParsedListen;
  });

/**
 * Resolve the account's default VPC and its per-AZ default subnets. Shared by
 * the composition step (target group / security group VPC, owned ALB subnets)
 * and the provider's network resolution.
 */
const lookupDefaultNetwork = Effect.gen(function* () {
  const vpc = yield* ec2.describeVpcs
    .items({
      Filters: [{ Name: "isDefault", Values: ["true"] }],
    })
    .pipe(
      Stream.filter((v) => v.IsDefault === true),
      Stream.runHead,
      Effect.map(Option.getOrUndefined),
    );
  if (!vpc?.VpcId) {
    return yield* Effect.die(
      new Error(
        "AWS.ECS.Service: no default VPC in this account/region — pass `vpcId` and `subnets` explicitly",
      ),
    );
  }
  const subnetIds = yield* ec2.describeSubnets
    .items({
      Filters: [
        { Name: "vpc-id", Values: [vpc.VpcId] },
        { Name: "default-for-az", Values: ["true"] },
      ],
    })
    .pipe(
      Stream.map((s) => s.SubnetId),
      Stream.filter((s): s is string => s !== undefined),
      Stream.runCollect,
      Effect.map((chunk) => Array.from(chunk)),
    );
  if (subnetIds.length === 0) {
    return yield* Effect.die(
      new Error(
        "AWS.ECS.Service: the default VPC has no default subnets — pass `subnets` explicitly",
      ),
    );
  }
  return { vpcId: vpc.VpcId, subnets: subnetIds };
});

const toValuesArray = (value: string | string[] | undefined) =>
  value === undefined ? undefined : Array.isArray(value) ? value : [value];

/** Flat rule conditions → the `ELBv2.ListenerRule` condition shape. */
const ruleConditionsOf = (rule: ServiceLoadBalancerRule): ListenerRuleCondition[] => {
  const conditions: ListenerRuleCondition[] = [];
  const path = toValuesArray(rule.path);
  if (path) conditions.push({ pathPattern: { values: path } });
  const host = toValuesArray(rule.host);
  if (host) conditions.push({ hostHeader: { values: host } });
  if (rule.header) {
    conditions.push({
      httpHeader: { name: rule.header.name, values: rule.header.values },
    });
  }
  if (rule.query) conditions.push({ queryString: { values: rule.query } });
  return conditions;
};

/** IP protocols a listener protocol admits through the managed security group. */
const sgProtocolsOf = (protocol: string): string[] =>
  protocol === "udp" ? ["udp"] : protocol === "tcp_udp" ? ["tcp", "udp"] : ["tcp"];

interface ManagedSgPort {
  port: number;
  ipProtocol: string;
}

/**
 * Ingress rules for the managed security group. `dynamicPort` is the main
 * container's port when it is only known as an Output (the `task:` form) —
 * the rule list is then computed at resolve time so ports can be deduped.
 */
const managedSgIngress = (
  staticPorts: ManagedSgPort[],
  dynamicPort: unknown,
): SecurityGroupRuleData[] => {
  const rulesOf = (entries: ManagedSgPort[]): SecurityGroupRuleData[] => {
    const seen = new Set<string>();
    return entries.flatMap(({ port, ipProtocol }) => {
      const dedupeKey = `${ipProtocol}:${port}`;
      if (seen.has(dedupeKey)) {
        return [];
      }
      seen.add(dedupeKey);
      return [
        {
          ipProtocol,
          fromPort: port,
          toPort: port,
          cidrIpv4: "0.0.0.0/0",
          description: "Alchemy-managed ECS service ingress",
        },
      ];
    });
  };
  if (dynamicPort === undefined) {
    return rulesOf(staticPorts);
  }
  if (typeof dynamicPort === "number") {
    return rulesOf([...staticPorts, { port: dynamicPort, ipProtocol: "tcp" }]);
  }
  return Output.map(dynamicPort as Output.Output<number>, (port) =>
    rulesOf([...staticPorts, { port, ipProtocol: "tcp" }]),
  ) as unknown as SecurityGroupRuleData[];
};

/** Normalize the {@link ServiceCapacityConfig} sugar into a capacity provider strategy. */
const capacityProviderStrategyOf = (
  capacity: ServiceCapacityConfig,
): ecs.CapacityProviderStrategyItem[] =>
  capacity === "spot"
    ? [{ capacityProvider: "FARGATE_SPOT", weight: 1 }]
    : [
        ...(capacity.fargate
          ? [
              {
                capacityProvider: "FARGATE",
                weight: capacity.fargate.weight,
                base: capacity.fargate.base,
              },
            ]
          : []),
        ...(capacity.spot
          ? [
              {
                capacityProvider: "FARGATE_SPOT",
                weight: capacity.spot.weight,
                base: capacity.spot.base,
              },
            ]
          : []),
      ];

/**
 * Compose the Cloud Map service for {@link ServicePropsBase.serviceRegistry}
 * and rewrite it into the raw `serviceRegistries` list.
 */
const composeServiceRegistry = (id: string, props: ServiceProps) =>
  Effect.gen(function* () {
    const registry = props.serviceRegistry!;
    const namespace = registry.namespace;
    const isHttpNamespace =
      typeof namespace === "object" &&
      namespace !== null &&
      "Type" in namespace &&
      (namespace as { Type?: unknown }).Type === "AWS.CloudMap.HttpNamespace";
    const cloudMapService = yield* CloudMapService("ServiceRegistry", {
      namespaceId: namespace.namespaceId,
      dnsRecords: isHttpNamespace
        ? undefined
        : [
            registry.port !== undefined
              ? { type: "SRV", ttl: "10 seconds" }
              : { type: "A", ttl: "10 seconds" },
          ],
      tags: props.tags,
    });
    return {
      ...props,
      serviceRegistry: undefined,
      serviceRegistries: [
        ...(props.serviceRegistries ?? []),
        {
          registryArn: cloudMapService.serviceArn as unknown as string,
          port: registry.port,
        },
      ],
    } as ServiceProps;
  });

/**
 * The `transformProps` hook: normalize the `capacity` sugar, then — when
 * service discovery or managed load balancing is requested — compose the
 * Cloud Map / ELBv2 (and security group) child resources under the service's
 * namespace and rewrite the props to reference their outputs (the internal
 * `ingress` prop and `serviceRegistries`). A no-op at runtime.
 */
const transformServiceProps = (
  id: string,
  props: ServiceProps,
): Effect.Effect<ServiceProps, unknown, any> =>
  Effect.gen(function* () {
    // Composition is a plan/deploy concern — never runs inside bundles.
    if (globalThis.__ALCHEMY_RUNTIME__) {
      return props;
    }
    let next: ServiceProps = props;
    if (next.capacity !== undefined) {
      next = {
        ...next,
        capacityProviderStrategy:
          next.capacityProviderStrategy ?? capacityProviderStrategyOf(next.capacity),
        capacity: undefined,
      };
    }
    const lbProp =
      next.loadBalancer !== undefined ? next.loadBalancer : ((next.public ?? false) as boolean);
    const wantsIngress = lbProp !== false && lbProp !== undefined;
    if (!wantsIngress && next.serviceRegistry === undefined) {
      return next;
    }
    return yield* Effect.gen(function* () {
      if (next.serviceRegistry !== undefined) {
        next = yield* composeServiceRegistry(id, next);
      }
      if (wantsIngress) {
        next = yield* composeManagedIngress(
          id,
          next,
          lbProp as true | Listener | ServiceLoadBalancerConfig,
        );
      }
      return next;
    }).pipe(Namespace.push(id));
  });

// Tasks in `host`/`bridge` mode have no ENI of their own.
const usesAwsvpc = (props: ServiceProps) =>
  !("networkMode" in props) || (props.networkMode ?? "awsvpc") === "awsvpc";

const composeManagedIngress = (
  id: string,
  props: ServiceProps,
  lbProp: true | Listener | ServiceLoadBalancerConfig,
) =>
  Effect.gen(function* () {
    const config: ServiceLoadBalancerConfig =
      lbProp === true ? {} : isELBv2Listener(lbProp) ? { listener: lbProp } : lbProp;
    const rules = config.rules ?? (config.listener !== undefined ? [{}] : []);

    // ── classify ownership ───────────────────────────────────────────────
    const hasSharedRefs =
      config.listener !== undefined || rules.some((rule) => isELBv2Listener(rule.listen));
    const hasOwnedStrings = rules.some((rule) => typeof rule.listen === "string");
    if (hasSharedRefs && hasOwnedStrings) {
      return yield* new MixedListenerOwnership({
        serviceId: id,
        message: `AWS.ECS.Service "${id}": rules mix owned "<port>/<protocol>" listen strings with shared ELBv2.Listener references — a service either owns its ALB (strings only) or attaches rules to shared listeners (references only)`,
      });
    }
    const owned = !hasSharedRefs;
    if (!owned && config.public !== undefined) {
      return yield* new OwnedOnlyLoadBalancerOption({
        serviceId: id,
        option: "public",
        message: `AWS.ECS.Service "${id}": \`public\` only applies to an owned load balancer — the shared listener's ALB controls its own scheme`,
      });
    }
    // `true`, a bare `{}`, or an owned config with zero rules: single default
    // listener forwarding to the container port.
    const trueLike = owned && rules.length === 0;

    // ── protocol family: ALB (http/https) vs NLB (tcp/udp/tls/tcp_udp) ──
    const families = new Set<"application" | "network">();
    for (const rule of rules) {
      const specs: [string | Listener | undefined, string][] = [
        [rule.listen, "listen"],
        [rule.forward, "forward"],
        [rule.redirect, "redirect"],
      ];
      for (const [spec, kind] of specs) {
        if (typeof spec === "string") {
          const parsed = yield* parseListenSpec(id, spec, kind);
          families.add(NETWORK_PROTOCOLS.has(parsed.protocol) ? "network" : "application");
        }
      }
    }
    if (families.size > 1) {
      return yield* new MixedLoadBalancerProtocols({
        serviceId: id,
        message: `AWS.ECS.Service "${id}": rules mix application (http/https) and network (tcp/udp/tls/tcp_udp) protocols — one service composes exactly one load balancer type`,
      });
    }
    const lbType: "application" | "network" = families.has("network") ? "network" : "application";
    if (lbType === "network") {
      // NLB listeners route by port alone: no rule conditions, no redirect
      // actions, no attaching rules to shared listeners, and exactly one
      // rule per listener port (it becomes the listener's default action).
      const failNetworkRule = (ruleIndex: number, reason: string) =>
        Effect.fail(
          new NetworkListenerRuleUnsupported({
            serviceId: id,
            ruleIndex,
            message: `AWS.ECS.Service "${id}": rule ${ruleIndex} ${reason}`,
          }),
        );
      if (!owned) {
        return yield* failNetworkRule(
          0,
          "uses network (tcp/udp/tls/tcp_udp) protocols with a shared listener — NLB listeners have no rules, so network ingress is always owned",
        );
      }
      const seenPorts = new Set<number>();
      for (const [index, rule] of rules.entries()) {
        if (typeof rule.listen !== "string") {
          return yield* failNetworkRule(
            index,
            "must declare an explicit `listen` — network listeners have no default",
          );
        }
        if (rule.redirect !== undefined) {
          return yield* failNetworkRule(index, "sets `redirect` — NLB listeners cannot redirect");
        }
        if (
          rule.path !== undefined ||
          rule.host !== undefined ||
          rule.header !== undefined ||
          rule.query !== undefined
        ) {
          return yield* failNetworkRule(
            index,
            "sets routing conditions — NLB listeners route by port alone",
          );
        }
        const { port } = yield* parseListenSpec(id, rule.listen, "listen");
        if (seenPorts.has(port)) {
          return yield* failNetworkRule(
            index,
            `re-declares listener port ${port} — a network listener forwards to exactly one target group`,
          );
        }
        seenPorts.add(port);
      }
    }

    // ── custom domain (owned only): hosted zones + certificate ──────────
    const domain =
      config.domain === undefined
        ? undefined
        : typeof config.domain === "string"
          ? { name: config.domain }
          : config.domain;
    if (domain !== undefined && !owned) {
      return yield* new OwnedOnlyLoadBalancerOption({
        serviceId: id,
        option: "domain",
        message: `AWS.ECS.Service "${id}": \`domain\` only applies to an owned load balancer — the shared listener's ALB owns its DNS and certificates`,
      });
    }
    let certificateArn: string | undefined = props.certificateArn;
    const domainNames = domain !== undefined ? [domain.name, ...(domain.aliases ?? [])] : [];
    const domainZones = new Map<string, string>();
    // Route 53 (the default) needs a matching hosted zone up front; other
    // DNS hosts (e.g. Cloudflare) infer their zone at reconcile time.
    const usesRoute53 = domain !== undefined && isRoute53Dns(domain.dns);
    const pinnedZoneId = domain?.dns?.zone as string | undefined;
    if (domain !== undefined) {
      for (const name of usesRoute53 ? domainNames : []) {
        const zoneId = pinnedZoneId ?? (yield* findPublicHostedZoneId(name));
        if (zoneId === undefined) {
          return yield* new ServiceHostedZoneNotFound({
            serviceId: id,
            domainName: name,
            message: `AWS.ECS.Service "${id}": no public Route 53 hosted zone contains '${name}' — create the hosted zone first (alias records land in it)`,
          });
        }
        domainZones.set(name, zoneId);
      }
      if (domain.cert !== undefined) {
        certificateArn = domain.cert;
      } else {
        // DNS-validated certificate in the service's own region (an ALB/NLB
        // listener requires an in-region certificate).
        const { region } = yield* AWSEnvironment.current;