@highstate/k8s 0.9.18 → 0.9.20

package/src/service.ts

@@ -1,27 +1,29 @@
-import type { k8s, network } from "@highstate/library"
-import { core, types } from "@pulumi/kubernetes"
+import { filterEndpoints, l4EndpointToString, parseL3Endpoint } from "@highstate/common"
+import { check, getOrCreate } from "@highstate/contract"
+import { k8s, type network } from "@highstate/library"
 import {
-  ComponentResource,
-  normalize,
-  output,
-  Output,
   type ComponentResourceOptions,
   type Input,
   type Inputs,
+  interpolate,
+  normalize,
+  type Output,
+  output,
+  toPromise,
 } from "@highstate/pulumi"
-import { omit, uniqueBy } from "remeda"
+import { core, type types } from "@pulumi/kubernetes"
 import { deepmerge } from "deepmerge-ts"
-import { filterEndpoints, l4EndpointToString, parseL3Endpoint } from "@highstate/common"
+import { omit, uniqueBy } from "remeda"
+import { Namespace } from "./namespace"
 import {
   commonExtraArgs,
+  getProvider,
   mapMetadata,
-  resourceIdToString,
-  type CommonArgs,
-  type ResourceId,
-  type SelectorLike,
+  ScopedResource,
+  type ScopedResourceArgs,
 } from "./shared"
 
-export type ServiceArgs = CommonArgs & {
+export type ServiceArgs = ScopedResourceArgs & {
   /**
    * The port to expose the service on.
    */
@@ -32,64 +34,17 @@ export type ServiceArgs = CommonArgs & {
    *
    * The type of the service will be determined automatically based on the cluster.
    */
-  external?: boolean
+  external?: Input<boolean>
 } & types.input.core.v1.ServiceSpec
 
-const serviceExtraArgs = [...commonExtraArgs, "port", "ports", "external"] as const
-
-export type ServiceEndpointMetadata = {
-  clusterId: string
-  name: string
-  namespace: string
-  selector: SelectorLike
-  targetPort: string | number
-}
-
-/**
- * Checks if the endpoint has service metadata.
- *
- * Alters the type of the endpoint to include the service metadata if it exists.
- *
- * @param endpoint The endpoint to check.
- * @returns True if the endpoint has service metadata, false otherwise.
- */
-export function hasServiceMetadata(
-  endpoint: network.L3Endpoint,
-): endpoint is network.L3Endpoint & { metadata: { k8sService: ServiceEndpointMetadata } } {
-  return endpoint.metadata?.k8sService !== undefined
-}
-
-/**
- * Returns the service metadata of the endpoint.
- *
- * @param endpoint The endpoint to get the service metadata from.
- * @returns The service metadata of the endpoint, or undefined if it doesn't exist.
- */
-export function getServiceMetadata(
-  endpoint: network.L3Endpoint,
-): ServiceEndpointMetadata | undefined {
-  return endpoint.metadata?.k8sService as ServiceEndpointMetadata
+export type CreateOrGetServiceArgs = ServiceArgs & {
+  /**
+   * The service entity to patch/retrieve.
+   */
+  existing: Input<k8s.Service> | undefined
 }
 
-/**
- * Adds service metadata to the endpoint.
- *
- * @param endpoint The endpoint to add the metadata to.
- * @param metadata The metadata to add.
- * @returns The endpoint with the added metadata.
- */
-export function withServiceMetadata<TEdnpoint extends network.L34Endpoint>(
-  endpoint: TEdnpoint,
-  metadata: ServiceEndpointMetadata,
-): TEdnpoint & { metadata: { k8sService: ServiceEndpointMetadata } } {
-  return {
-    ...endpoint,
-    metadata: {
-      ...endpoint.metadata,
-      k8sService: metadata,
-    },
-  }
-}
+const serviceExtraArgs = [...commonExtraArgs, "port", "ports", "external"] as const
 
 /**
  * Checks if the endpoint is from the given cluster.
@@ -98,29 +53,30 @@ export function withServiceMetadata<TEdnpoint extends network.L34Endpoint>(
  * @param cluster The cluster to check against.
  * @returns True if the endpoint is from the cluster, false otherwise.
  */
-export function isFromCluster(
+export function isEndpointFromCluster(
   endpoint: network.L3Endpoint,
   cluster: k8s.Cluster,
-): endpoint is network.L3Endpoint & { metadata: { k8sService: ServiceEndpointMetadata } } {
-  return getServiceMetadata(endpoint)?.clusterId === cluster.id
+): endpoint is k8s.ServiceEndpoint {
+  return (
+    check(k8s.serviceEndpointSchema, endpoint) &&
+    endpoint.metadata["k8s.service"].clusterId === cluster.id
+  )
 }
 
-export abstract class Service extends ComponentResource {
+/**
+ * Represents a Kubernetes Service resource with endpoints and metadata.
+ */
+export abstract class Service extends ScopedResource {
   protected constructor(
     type: string,
     name: string,
     args: Inputs,
     opts: ComponentResourceOptions | undefined,
 
-    /**
-     * The cluster info associated with the service.
-     */
-    readonly cluster: Output<k8s.Cluster>,
-
-    /**
-     * The metadata of the underlying Kubernetes service.
-     */
-    readonly metadata: Output<types.output.meta.v1.ObjectMeta>,
+    apiVersion: Output<string>,
+    kind: Output<string>,
+    namespace: Output<Namespace>,
+    metadata: Output<types.output.meta.v1.ObjectMeta>,
 
     /**
      * The spec of the underlying Kubernetes service.
@@ -132,7 +88,7 @@ export abstract class Service extends ComponentResource {
      */
     readonly status: Output<types.output.core.v1.ServiceStatus>,
   ) {
-    super(type, name, args, opts)
+    super(type, name, args, opts, apiVersion, kind, namespace, metadata)
   }
 
   /**
@@ -140,57 +96,135 @@ export abstract class Service extends ComponentResource {
    */
   get entity(): Output<k8s.Service> {
     return output({
-      type: "k8s.service",
+      type: "service",
       clusterId: this.cluster.id,
+      clusterName: this.cluster.name,
       metadata: this.metadata,
       endpoints: this.endpoints,
     })
   }
 
-  static create(name: string, args: ServiceArgs, opts: ComponentResourceOptions): Service {
+  /**
+   * Creates a new service.
+   */
+  static create(name: string, args: ServiceArgs, opts?: ComponentResourceOptions): Service {
     return new CreatedService(name, args, opts)
   }
 
-  static wrap(
+  /**
+   * Creates a new service or patches an existing one.
+   *
+   * @param name The name of the resource. May not be the same as the service name.
+   * @param args The arguments to create or patch the service with.
+   * @param opts Optional resource options.
+   */
+  static createOrPatch(
     name: string,
-    service: Input<core.v1.Service>,
-    cluster: Input<k8s.Cluster>,
+    args: CreateOrGetServiceArgs,
     opts?: ComponentResourceOptions,
   ): Service {
-    return new WrappedService(name, service, cluster, opts)
+    if (args.existing) {
+      return new ServicePatch(name, {
+        ...args,
+        name: output(args.existing).metadata.name,
+        namespace: Namespace.forResourceAsync(args.existing, output(args.namespace).cluster),
+      })
+    }
+
+    return new CreatedService(name, args, opts)
   }
 
-  static get(
+  /**
+   * Creates a new service or gets an existing one.
+   *
+   * @param name The name of the resource. May not be the same as the service name. Will not be used when existing service is retrieved.
+   * @param args The arguments to create or get the service with.
+   * @param opts Optional resource options.
+   */
+  static async createOrGet(
     name: string,
-    id: ResourceId,
-    cluster: Input<k8s.Cluster>,
+    args: CreateOrGetServiceArgs,
     opts?: ComponentResourceOptions,
-  ): Service {
-    return new ExternalService(name, id, cluster, opts)
+  ): Promise<Service> {
+    if (args.existing) {
+      return await Service.forAsync(args.existing, output(args.namespace).cluster)
+    }
+
+    return new CreatedService(name, args, opts)
   }
 
-  static of(
-    name: string,
-    entity: Input<k8s.Service>,
-    cluster: Input<k8s.Cluster>,
-    opts?: ComponentResourceOptions,
-  ): Service {
-    return new ExternalService(
-      name,
-      output(entity).metadata,
-      output({ cluster, entity }).apply(({ cluster, entity }) => {
-        if (cluster.id !== entity.clusterId) {
-          throw new Error(
-            `Cluster mismatch when wrapping service "${name}": "${cluster.id}" != "${entity.clusterId}"`,
-          )
-        }
-
-        return cluster
-      }),
-      opts,
+  /**
+   * Patches an existing service.
+   *
+   * Will throw an error if the service does not exist.
+   *
+   * @param name The name of the resource. May not be the same as the service name.
+   * @param args The arguments to patch the service with.
+   * @param opts Optional resource options.
+   */
+  static patch(name: string, args: ServiceArgs, opts?: ComponentResourceOptions): Service {
+    return new ServicePatch(name, args, opts)
+  }
+
+  /**
+   * Wraps an existing Kubernetes service.
+   */
+  static wrap(name: string, args: WrappedServiceArgs, opts?: ComponentResourceOptions): Service {
+    return new WrappedService(name, args, opts)
+  }
+
+  /**
+   * Gets an existing service.
+   *
+   * Will throw an error if the service does not exist.
+   */
+  static get(name: string, args: ExternalServiceArgs, opts?: ComponentResourceOptions): Service {
+    return new ExternalService(name, args, opts)
+  }
+
+  private static readonly serviceCache = new Map<string, Service>()
+
+  /**
+   * Gets an existing service for a given entity.
+   * Prefer this method over `get` when possible.
+   *
+   * It automatically names the resource with the following format: `{clusterName}.{namespace}.{name}.{clusterId}`.
+   *
+   * This method is idempotent and will return the same instance for the same entity.
+   *
+   * @param entity The entity to get the service for.
+   * @param cluster The cluster where the service is located.
+   */
+  static for(entity: k8s.Service, cluster: Input<k8s.Cluster>): Service {
+    return getOrCreate(
+      Service.serviceCache,
+      `${entity.clusterName}.${entity.metadata.namespace}.${entity.metadata.name}.${entity.clusterId}`,
+      name => {
+        return Service.get(name, {
+          name: entity.metadata.name,
+          namespace: Namespace.forResourceAsync(entity, cluster),
+        })
+      },
     )
   }
 
+  /**
+   * Gets an existing service for a given entity.
+   * Prefer this method over `get` when possible.
+   *
+   * It automatically names the resource with the following format: `{clusterName}.{namespace}.{name}.{clusterId}`.
+   *
+   * This method is idempotent and will return the same instance for the same entity.
+   *
+   * @param entity The entity to get the service for.
+   * @param cluster The cluster where the service is located.
+   */
+  static async forAsync(entity: Input<k8s.Service>, cluster: Input<k8s.Cluster>): Promise<Service> {
+    const resolvedEntity = await toPromise(entity)
+
+    return Service.for(resolvedEntity, output(cluster))
+  }
+
   /**
    * Returns the endpoints of the service applying the given filter.
    *
@@ -199,30 +233,29 @@ export abstract class Service extends ComponentResource {
    * @param filter If specified, the endpoints are filtered based on the given filter.
    * @returns The endpoints of the service.
    */
-  filterEndpoints(filter?: network.EndpointFilter): Output<network.L4Endpoint[]> {
-    return output({ endpoints: this.endpoints }).apply(({ endpoints }) => {
-      return filterEndpoints(endpoints, filter)
-    })
+  filterEndpoints(filter?: network.EndpointFilter): Output<k8s.ServiceEndpoint[]> {
+    return output(this.endpoints).apply(endpoints => filterEndpoints(endpoints, filter))
   }
 
   /**
    * Returns the endpoints of the service including both internal and external endpoints.
    */
-  get endpoints(): Output<network.L4Endpoint[]> {
+  get endpoints(): Output<k8s.ServiceEndpoint[]> {
     return output({
       cluster: this.cluster,
       metadata: this.metadata,
       spec: this.spec,
       status: this.status,
     }).apply(({ cluster, metadata, spec, status }) => {
-      const endpointMetadata = {
-        k8sService: {
+      const endpointMetadata: k8s.EndpointServiceMetadata = {
+        "k8s.service": {
           clusterId: cluster.id,
+          clusterName: cluster.name,
           name: metadata.name,
           namespace: metadata.namespace,
           selector: spec.selector,
           targetPort: spec.ports[0].targetPort ?? spec.ports[0].port,
-        } satisfies ServiceEndpointMetadata,
+        },
       }
 
       const clusterIpEndpoints = spec.clusterIPs?.map(ip => ({
@@ -270,33 +303,48 @@ export abstract class Service extends ComponentResource {
           ...(loadBalancerEndpoints ?? []),
           ...(nodePortEndpoints ?? []),
         ],
-        endpoint => l4EndpointToString(endpoint),
+        l4EndpointToString,
       )
     })
   }
 }
 
+/**
+ * Creates the service spec configuration based on arguments and cluster settings.
+ *
+ * @param args The service arguments containing port and external configuration.
+ * @param cluster The cluster where the service will be created.
+ * @returns The service spec configuration.
+ */
+function createServiceSpec(args: ServiceArgs, cluster: k8s.Cluster) {
+  return output(args).apply(args => {
+    return deepmerge(
+      {
+        ports: normalize(args.port, args.ports),
+
+        externalIPs: args.external
+          ? args.externalIPs
+            ? args.externalIPs
+            : cluster.externalIps
+          : normalize(undefined, args.externalIPs),
+
+        type: getServiceType(args, cluster),
+      },
+      omit(args, serviceExtraArgs),
+    )
+  })
+}
+
 class CreatedService extends Service {
   constructor(name: string, args: ServiceArgs, opts?: ComponentResourceOptions) {
-    const service = output(args).apply(args => {
+    const service = output(args.namespace).cluster.apply(cluster => {
       return new core.v1.Service(
         name,
         {
           metadata: mapMetadata(args, name),
-          spec: deepmerge(
-            {
-              ports: normalize(args.port, args.ports),
-
-              externalIPs: args.external
-                ? (args.externalIPs ?? args.cluster.externalIps)
-                : args.cluster.externalIps,
-
-              type: getServiceType(args, args.cluster),
-            },
-            omit(args, serviceExtraArgs),
-          ),
+          spec: createServiceSpec(args, cluster),
         },
-        { parent: this, ...opts },
+        { ...opts, parent: this, provider: getProvider(cluster) },
       )
     })
 
@@ -306,7 +354,9 @@ class CreatedService extends Service {
       args,
       opts,
 
-      output(args.cluster),
+      service.apiVersion,
+      service.kind,
+      output(args.namespace),
       service.metadata,
       service.spec,
       service.status,
@@ -314,50 +364,96 @@ class CreatedService extends Service {
   }
 }
 
+class ServicePatch extends Service {
+  constructor(name: string, args: ServiceArgs, opts?: ComponentResourceOptions) {
+    const service = output(args.namespace).cluster.apply(cluster => {
+      return new core.v1.ServicePatch(
+        name,
+        {
+          metadata: mapMetadata(args, name),
+          spec: createServiceSpec(args, cluster),
+        },
+        { ...opts, parent: this, provider: getProvider(cluster) },
+      )
+    })
+
+    super(
+      "highstate:k8s:ServicePatch",
+      name,
+      args,
+      opts,
+
+      service.apiVersion,
+      service.kind,
+      output(args.namespace),
+      service.metadata,
+      service.spec,
+      service.status,
+    )
+  }
+}
+
+export type WrappedServiceArgs = {
+  /**
+   * The underlying Kubernetes service to wrap.
+   */
+  service: Input<core.v1.Service>
+
+  /**
+   * The namespace where the service is located.
+   */
+  namespace: Input<Namespace>
+}
+
 class WrappedService extends Service {
-  constructor(
-    name: string,
-    service: Input<core.v1.Service>,
-    cluster: Input<k8s.Cluster>,
-    opts?: ComponentResourceOptions,
-  ) {
+  constructor(name: string, args: WrappedServiceArgs, opts?: ComponentResourceOptions) {
     super(
       "highstate:k8s:WrappedService",
       name,
-      { service, clusterInfo: cluster },
+      args,
       opts,
 
-      output(cluster),
-      output(service).metadata,
-      output(service).spec,
-      output(service).status,
+      output(args.service).apiVersion,
+      output(args.service).kind,
+      output(args.namespace),
+      output(args.service).metadata,
+      output(args.service).spec,
+      output(args.service).status,
     )
   }
 }
 
+export type ExternalServiceArgs = {
+  /**
+   * The name of the service to get.
+   */
+  name: Input<string>
+
+  /**
+   * The namespace of the service to get.
+   */
+  namespace: Input<Namespace>
+}
+
 class ExternalService extends Service {
-  constructor(
-    name: string,
-    id: Input<ResourceId>,
-    cluster: Input<k8s.Cluster>,
-    opts?: ComponentResourceOptions,
-  ) {
-    const service = output(id).apply(id => {
+  constructor(name: string, args: ExternalServiceArgs, opts?: ComponentResourceOptions) {
+    const service = output(args.namespace).cluster.apply(cluster => {
       return core.v1.Service.get(
-        //
         name,
-        resourceIdToString(id),
-        { ...opts, parent: this },
+        interpolate`${output(args.namespace).metadata.name}/${args.name}`,
+        { ...opts, parent: this, provider: getProvider(cluster) },
       )
     })
 
     super(
       "highstate:k8s:ExternalService",
       name,
-      { id, cluster },
+      args,
       opts,
 
-      output(cluster),
+      service.apiVersion,
+      service.kind,
+      output(args.namespace),
       service.metadata,
       service.spec,
       service.status,
@@ -365,6 +461,12 @@ class ExternalService extends Service {
   }
 }
 
+/**
+ * Maps a container port to a service port.
+ *
+ * @param port The container port to map.
+ * @returns The corresponding service port configuration.
+ */
 export function mapContainerPortToServicePort(
   port: types.input.core.v1.ContainerPort,
 ): types.input.core.v1.ServicePort {
@@ -376,6 +478,12 @@ export function mapContainerPortToServicePort(
   }
 }
 
+/**
+ * Maps a service to a label selector.
+ *
+ * @param service The service to extract the label selector from.
+ * @returns The label selector based on the service's selector.
+ */
 export function mapServiceToLabelSelector(
   service: core.v1.Service,
 ): types.input.meta.v1.LabelSelector {
@@ -384,6 +492,13 @@ export function mapServiceToLabelSelector(
   }
 }
 
+/**
+ * Determines the appropriate service type based on the service arguments and cluster configuration.
+ *
+ * @param service The service configuration containing type and external properties.
+ * @param cluster The cluster where the service will be created.
+ * @returns The service type to use.
+ */
 export function getServiceType(
   service: Pick<ServiceArgs, "type" | "external"> | undefined,
   cluster: k8s.Cluster,
@@ -398,3 +513,18 @@ export function getServiceType(
 
   return cluster.quirks?.externalServiceType === "LoadBalancer" ? "LoadBalancer" : "NodePort"
 }
+
+/**
+ * Converts a network L4 endpoint to a Kubernetes service port.
+ *
+ * @param endpoint The L4 endpoint to convert.
+ * @returns The corresponding Kubernetes service port configuration.
+ */
+export function l4EndpointToServicePort(
+  endpoint: network.L4Endpoint,
+): types.input.core.v1.ServicePort {
+  return {
+    port: endpoint.port,
+    protocol: endpoint.protocol.toUpperCase(),
+  }
+}