@highstate/common 0.9.3 → 0.9.5

package/src/shared/dns.ts

@@ -1,14 +1,26 @@
-import type { dns } from "@highstate/library"
+import type { ArrayPatchMode, dns, network } from "@highstate/library"
 import {
   ComponentResource,
+  normalize,
   output,
   Output,
   Resource,
+  toPromise,
   type Input,
+  type InputArray,
+  type InputOrArray,
   type ResourceOptions,
   type Unwrap,
 } from "@highstate/pulumi"
-import { capitalize } from "remeda"
+import { capitalize, groupBy, uniqueBy } from "remeda"
+import { Command, type CommandHost } from "./command"
+import {
+  filterEndpoints,
+  l34EndpointToString,
+  l3EndpointToString,
+  parseL3Endpoint,
+  type InputL3Endpoint,
+} from "./network"
 
 export type DnsRecordArgs = {
   /**
@@ -24,13 +36,15 @@ export type DnsRecordArgs = {
 
   /**
    * The type of the DNS record.
+   *
+   * If not provided, will be automatically detected based on the value.
    */
-  type: Input<string>
+  type?: Input<string>
 
   /**
    * The value of the DNS record.
    */
-  value: Input<string>
+  value: Input<InputL3Endpoint>
 
   /**
    * Whether the DNS record is proxied (e.g. to provide DDoS protection).
@@ -53,15 +67,53 @@ export type DnsRecordArgs = {
    * Only used for some DNS record types (e.g. MX).
    */
   priority?: Input<number>
+
+  /**
+   * Wait for the DNS record to be created/updated at the specified environment(s) before continuing.
+   */
+  waitAt?: InputOrArray<CommandHost>
 }
 
-export type DnsRecordSetArgs = Omit<DnsRecordArgs, "provider"> & {
+export type ResolvedDnsRecordArgs = Unwrap<Omit<DnsRecordArgs, "value" | "type">> & {
+  /**
+   * The value of the DNS record.
+   */
+  value: string
+
+  /**
+   * The type of the DNS record.
+   */
+  type: string
+}
+
+export type DnsRecordSetArgs = Omit<DnsRecordArgs, "provider" | "value"> & {
   /**
    * The DNS providers to use to create the DNS records.
    *
    * If multiple providers matched the specified domain, multiple DNS records will be created.
    */
   providers: Input<dns.Provider[]>
+
+  /**
+   * The value of the DNS record.
+   */
+  value?: Input<InputL3Endpoint>
+
+  /**
+   * The values of the DNS records.
+   */
+  values?: InputArray<InputL3Endpoint>
+}
+
+function getTypeByEndpoint(endpoint: network.L3Endpoint): string {
+  switch (endpoint.type) {
+    case "ipv4":
+      return "A"
+    case "ipv6":
+      return "AAAA"
+    case "hostname":
+      return "CNAME"
+  }
 }
 
 export abstract class DnsRecord extends ComponentResource {
@@ -70,17 +122,55 @@ export abstract class DnsRecord extends ComponentResource {
    */
   public readonly dnsRecord: Output<Resource>
 
-  constructor(name: string, args: DnsRecordArgs, opts?: ResourceOptions) {
+  /**
+   * The wait commands to be executed after the DNS record is created/updated.
+   *
+   * Use this field as a dependency for other resources.
+   */
+  public readonly waitCommands: Output<Command[]>
+
+  protected constructor(name: string, args: DnsRecordArgs, opts?: ResourceOptions) {
     super("highstate:common:DnsRecord", name, args, opts)
 
     this.dnsRecord = output(args).apply(args => {
-      return output(this.create(name, args, { ...opts, parent: this }))
+      const l3Endpoint = parseL3Endpoint(args.value)
+      const type = args.type ?? getTypeByEndpoint(l3Endpoint)
+
+      return output(
+        this.create(
+          name,
+          {
+            ...args,
+            type,
+            value: l3EndpointToString(l3Endpoint),
+          },
+          { ...opts, parent: this },
+        ),
+      )
+    })
+
+    this.waitCommands = output(args).apply(args => {
+      const waitAt = args.waitAt ? (Array.isArray(args.waitAt) ? args.waitAt : [args.waitAt]) : []
+
+      return waitAt.map(host => {
+        const hostname = host === "local" ? "local" : host.hostname
+
+        return new Command(
+          `${name}-wait-${hostname}`,
+          {
+            host,
+            create: `while ! getent hosts ${args.name} >/dev/null; do echo "Waiting for DNS record ${args.name} to be created"; sleep 5; done`,
+            triggers: [args.type, args.ttl, args.priority, args.proxied],
+          },
+          { parent: this },
+        )
+      })
     })
   }
 
   protected abstract create(
     name: string,
-    args: Unwrap<DnsRecordArgs>,
+    args: ResolvedDnsRecordArgs,
     opts?: ResourceOptions,
   ): Input<Resource>
 
@@ -99,26 +189,124 @@ export abstract class DnsRecord extends ComponentResource {
       return new implClass(name, args, opts)
     })
   }
+}
 
-  static createSet(
-    name: string,
-    args: DnsRecordSetArgs,
-    opts?: ResourceOptions,
-  ): Output<DnsRecord[]> {
-    return output(args).apply(args => {
+export class DnsRecordSet extends ComponentResource {
+  /**
+   * The underlying dns record resources.
+   */
+  public readonly dnsRecords: Output<DnsRecord[]>
+
+  /**
+   * The wait commands to be executed after the DNS records are created/updated.
+   */
+  public readonly waitCommands: Output<Command[]>
+
+  private constructor(name: string, records: Output<DnsRecord[]>, opts?: ResourceOptions) {
+    super("highstate:common:DnsRecordSet", name, records, opts)
+
+    this.dnsRecords = records
+
+    this.waitCommands = records.apply(records =>
+      records.flatMap(record => record.waitCommands),
+    ) as unknown as Output<Command[]>
+  }
+
+  static create(name: string, args: DnsRecordSetArgs, opts?: ResourceOptions): DnsRecordSet {
+    const records = output(args).apply(args => {
       const recordName = args.name ?? name
+      const values = normalize(args.value, args.values)
 
       return output(
         args.providers
           .filter(provider => recordName.endsWith(provider.domain))
-          .map(provider =>
-            DnsRecord.create(
-              `${name}.${provider.type}`,
-              { name: recordName, ...args, provider },
-              opts,
-            ),
-          ),
+          .flatMap(provider => {
+            return values.map(value => {
+              const l3Endpoint = parseL3Endpoint(value)
+
+              return DnsRecord.create(
+                `${provider.type}-from-${provider.name}-to-${l3EndpointToString(l3Endpoint)}`,
+                { name: recordName, ...args, value: l3Endpoint, provider },
+                opts,
+              )
+            })
+          }),
       )
     })
+
+    return new DnsRecordSet(name, records, opts)
+  }
+}
+
+/**
+ * Registers the DNS record set for the given endpoints and prepends the corresponding hostname endpoint to the list.
+ *
+ * Waits for the DNS record set to be created/updated before continuing.
+ *
+ * Ignores the "hostname" endpoints in the list.
+ *
+ * @param endpoints The list of endpoints to register. Will be modified in place.
+ * @param fqdn The FQDN to register the DNS record set for. If not provided, no DNS record set will be created and array will not be modified.
+ * @param fqdnEndpointFilter The filter to apply to the endpoints before passing them to the DNS record set. Does not apply to the resulted endpoint list.
+ * @param dnsProviders The DNS providers to use to create the DNS records.
+ */
+export async function updateEndpointsWithFqdn<TEndpoint extends network.L34Endpoint>(
+  endpoints: Input<TEndpoint[]>,
+  fqdn: string | undefined,
+  fqdnEndpointFilter: network.EndpointFilter,
+  patchMode: ArrayPatchMode,
+  dnsProviders: Input<dns.Provider[]>,
+): Promise<{ endpoints: TEndpoint[]; dnsRecordSet: DnsRecordSet | undefined }> {
+  const resolvedEndpoints = await toPromise(endpoints)
+
+  if (!fqdn) {
+    return {
+      endpoints: resolvedEndpoints as TEndpoint[],
+      dnsRecordSet: undefined,
+    }
+  }
+
+  const filteredEndpoints = filterEndpoints(resolvedEndpoints, fqdnEndpointFilter)
+
+  const dnsRecordSet = DnsRecordSet.create(fqdn, {
+    providers: dnsProviders,
+    values: filteredEndpoints,
+    waitAt: "local",
+  })
+
+  const portProtocolGroups = groupBy(filteredEndpoints, endpoint =>
+    endpoint.port ? `${endpoint.port}-${endpoint.protocol}` : "",
+  )
+
+  const newEndpoints: TEndpoint[] = []
+
+  for (const group of Object.values(portProtocolGroups)) {
+    newEndpoints.unshift({
+      type: "hostname",
+      hostname: fqdn,
+      visibility: group[0].visibility,
+      port: group[0].port,
+      protocol: group[0].protocol,
+    } as TEndpoint)
+  }
+
+  await toPromise(
+    dnsRecordSet.waitCommands.apply(waitCommands => waitCommands.map(command => command.stdout)),
+  )
+
+  if (patchMode === "prepend") {
+    return {
+      endpoints: uniqueBy(
+        //
+        [...newEndpoints, ...(resolvedEndpoints as TEndpoint[])],
+        endpoint => l34EndpointToString(endpoint),
+      ),
+      dnsRecordSet,
+    }
+  }
+
+  return {
+    endpoints: newEndpoints,
+    dnsRecordSet,
   }
 }

package/src/shared/index.ts

@@ -1,5 +1,5 @@
-export * from "./server"
+export * from "./command"
 export * from "./dns"
 export * from "./passwords"
 export * from "./ssh"
-export * from "./utils"
+export * from "./network"

package/src/shared/network.ts

@@ -0,0 +1,311 @@
+import type { ArrayPatchMode, network } from "@highstate/library"
+import { toPromise, type Input } from "@highstate/pulumi"
+import { uniqueBy } from "remeda"
+
+/**
+ * The L3 or L4 endpoint for some service.
+ *
+ * The format is: `[protocol://]endpoint[:port]`
+ */
+export type InputL34Endpoint = network.L34Endpoint | string
+
+/**
+ * The L3 endpoint for some service.
+ */
+export type InputL3Endpoint = network.L3Endpoint | string
+
+/**
+ * The L4 endpoint for some service.
+ */
+export type InputL4Endpoint = network.L4Endpoint | string
+
+/**
+ * Stringifies a L3 endpoint object into a string.
+ *
+ * @param l3Endpoint The L3 endpoint object to stringify.
+ * @returns The string representation of the L3 endpoint.
+ */
+export function l3EndpointToString(l3Endpoint: network.L3Endpoint): string {
+  switch (l3Endpoint.type) {
+    case "ipv4":
+      return l3Endpoint.address
+    case "ipv6":
+      return l3Endpoint.address
+    case "hostname":
+      return l3Endpoint.hostname
+  }
+}
+
+/**
+ * Stringifies a L4 endpoint object into a string.
+ *
+ * @param l4Endpoint The L4 endpoint object to stringify.
+ *
+ * @returns The string representation of the L4 endpoint.
+ */
+export function l4EndpointToString(l4Endpoint: network.L4Endpoint): string {
+  if (l4Endpoint.type === "ipv6") {
+    return `[${l4Endpoint.address}]:${l4Endpoint.port}`
+  }
+
+  return `${l3EndpointToString(l4Endpoint)}:${l4Endpoint.port}`
+}
+
+/**
+ * Stringifies a L3 or L4 endpoint object into a string.
+ *
+ * @param l34Endpoint The L3 or L4 endpoint object to stringify.
+ * @returns The string representation of the L3 or L4 endpoint.
+ */
+export function l34EndpointToString(l34Endpoint: network.L34Endpoint): string {
+  if (l34Endpoint.port) {
+    return l4EndpointToString(l34Endpoint)
+  }
+
+  return l3EndpointToString(l34Endpoint)
+}
+
+const L34_ENDPOINT_RE =
+  /^(?:(?<protocol>[a-z]+):\/\/)?(?:(?:\[?(?<ipv6>[0-9A-Fa-f:]+)\]?)|(?<ipv4>(?:\d{1,3}\.){3}\d{1,3})|(?<hostname>[a-zA-Z0-9-*]+(?:\.[a-zA-Z0-9-*]+)*))(?::(?<port>\d{1,5}))?$/
+
+/**
+ * Parses a L3 or L4 endpoint from a string.
+ *
+ * The format is `[protocol://]endpoint[:port]`.
+ *
+ * @param l34Endpoint The L3 or L4 endpoint string to parse.
+ * @returns The parsed L3 or L4 endpoint object.
+ */
+export function parseL34Endpoint(l34Endpoint: InputL34Endpoint): network.L34Endpoint {
+  if (typeof l34Endpoint === "object") {
+    return l34Endpoint
+  }
+
+  const match = l34Endpoint.match(L34_ENDPOINT_RE)
+  if (!match) {
+    throw new Error(`Invalid L3/L4 endpoint: "${l34Endpoint}"`)
+  }
+
+  const { protocol, ipv6, ipv4, hostname, port } = match.groups!
+
+  if (protocol && protocol !== "tcp" && protocol !== "udp") {
+    throw new Error(`Invalid L4 endpoint protocol: "${protocol}"`)
+  }
+
+  let visibility: network.EndpointVisibility = "public"
+
+  if (ipv4 && IPV4_PRIVATE_REGEX.test(ipv4)) {
+    visibility = "external"
+  } else if (ipv6 && IPV6_PRIVATE_REGEX.test(ipv6)) {
+    visibility = "external"
+  }
+
+  const fallbackProtocol = port ? "tcp" : undefined
+
+  return {
+    type: ipv6 ? "ipv6" : ipv4 ? "ipv4" : "hostname",
+    visibility,
+    address: ipv6 || ipv4,
+    hostname: hostname,
+    port: port ? parseInt(port, 10) : undefined,
+    protocol: protocol ? (protocol as network.L4Protocol) : fallbackProtocol,
+  } as network.L34Endpoint
+}
+
+/**
+ * Parses a L3 endpoint from a string.
+ *
+ * The same as `parseL34Endpoint`, but only for L3 endpoints and will throw an error if the endpoint contains a port.
+ *
+ * @param l3Endpoint The L3 endpoint string to parse.
+ * @returns The parsed L3 endpoint object.
+ */
+export function parseL3Endpoint(l3Endpoint: InputL3Endpoint): network.L3Endpoint {
+  if (typeof l3Endpoint === "object") {
+    return l3Endpoint
+  }
+
+  const parsed = parseL34Endpoint(l3Endpoint)
+
+  if (parsed.port) {
+    throw new Error(`Port cannot be specified in L3 endpoint: "${l3Endpoint}"`)
+  }
+
+  return parsed
+}
+
+/**
+ * Parses a L4 endpoint from a string.
+ *
+ * The same as `parseL34Endpoint`, but only for L4 endpoints and will throw an error if the endpoint does not contain a port.
+ */
+export function parseL4Endpoint(l4Endpoint: InputL4Endpoint): network.L4Endpoint {
+  if (typeof l4Endpoint === "object") {
+    return l4Endpoint
+  }
+
+  const parsed = parseL34Endpoint(l4Endpoint)
+
+  if (!parsed.port) {
+    throw new Error(`No port found in L4 endpoint: "${l4Endpoint}"`)
+  }
+
+  return parsed
+}
+
+const IPV4_PRIVATE_REGEX =
+  /^(?:10|127)(?:\.\d{1,3}){3}$|^(?:172\.1[6-9]|172\.2[0-9]|172\.3[0-1])(?:\.\d{1,3}){2}$|^(?:192\.168)(?:\.\d{1,3}){2}$/
+
+const IPV6_PRIVATE_REGEX =
+  /^(?:fc|fd)(?:[0-9a-f]{2}){0,2}::(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}$|^::(?:ffff:(?:10|127)(?:\.\d{1,3}){3}|(?:172\.1[6-9]|172\.2[0-9]|172\.3[0-1])(?:\.\d{1,3}){2}|(?:192\.168)(?:\.\d{1,3}){2})$/
+
+/**
+ * Helper function to get the input L3 endpoint from the raw endpoint or input endpoint.
+ *
+ * If neither is provided, an error is thrown.
+ *
+ * @param rawEndpoint The raw endpoint string to parse.
+ * @param inputEndpoint The input endpoint object to use if the raw endpoint is not provided.
+ * @returns The parsed L3 endpoint object.
+ */
+export async function requireInputL3Endpoint(
+  rawEndpoint: string | undefined,
+  inputEndpoint: Input<network.L3Endpoint> | undefined,
+): Promise<network.L3Endpoint> {
+  if (rawEndpoint) {
+    return parseL3Endpoint(rawEndpoint)
+  }
+
+  if (inputEndpoint) {
+    return toPromise(inputEndpoint)
+  }
+
+  throw new Error("No endpoint provided")
+}
+
+/**
+ * Helper function to get the input L4 endpoint from the raw endpoint or input endpoint.
+ *
+ * If neither is provided, an error is thrown.
+ *
+ * @param rawEndpoint The raw endpoint string to parse.
+ * @param inputEndpoint The input endpoint object to use if the raw endpoint is not provided.
+ * @returns The parsed L4 endpoint object.
+ */
+export async function requireInputL4Endpoint(
+  rawEndpoint: string | undefined,
+  inputEndpoint: Input<network.L4Endpoint> | undefined,
+): Promise<network.L4Endpoint> {
+  if (rawEndpoint) {
+    return parseL4Endpoint(rawEndpoint)
+  }
+
+  if (inputEndpoint) {
+    return toPromise(inputEndpoint)
+  }
+
+  throw new Error("No endpoint provided")
+}
+
+/**
+ * Convers L3 endpoint to L4 endpoint by adding a port and protocol.
+ *
+ * @param l3Endpoint The L3 endpoint to convert.
+ * @param port The port to add to the L3 endpoint.
+ * @param protocol The protocol to add to the L3 endpoint. Defaults to "tcp".
+ * @returns The L4 endpoint with the port and protocol added.
+ */
+export function l3ToL4Endpoint(
+  l3Endpoint: InputL3Endpoint,
+  port: number,
+  protocol: network.L4Protocol = "tcp",
+): network.L4Endpoint {
+  return {
+    ...parseL3Endpoint(l3Endpoint),
+    port,
+    protocol,
+  }
+}
+
+/**
+ * Filters the endpoints based on the given filter.
+ *
+ * @param endpoints The list of endpoints to filter.
+ * @param filter The filter to apply. If not provided, the endpoints will be filtered by the most accessible type: `public` > `external` > `internal`.
+ *
+ * @returns The filtered list of endpoints.
+ */
+export function filterEndpoints<TEndpoint extends network.L34Endpoint>(
+  endpoints: TEndpoint[],
+  filter?: network.EndpointFilter,
+): TEndpoint[] {
+  if (filter?.length) {
+    return endpoints.filter(endpoint => filter.includes(endpoint.visibility))
+  }
+
+  if (endpoints.some(endpoint => endpoint.visibility === "public")) {
+    return endpoints.filter(endpoint => endpoint.visibility === "public")
+  }
+
+  if (endpoints.some(endpoint => endpoint.visibility === "external")) {
+    return endpoints.filter(endpoint => endpoint.visibility === "external")
+  }
+
+  // in this case all endpoints are already internal
+  return endpoints
+}
+
+/**
+ * Converts a L3 endpoint to CIDR notation.
+ *
+ * If the endpoint is a hostname, an error is thrown.
+ *
+ * @param l3Endpoint The L3 endpoint to convert.
+ * @returns The CIDR notation of the L3 endpoint.
+ */
+export function l3EndpointToCidr(l3Endpoint: network.L3Endpoint): string {
+  switch (l3Endpoint.type) {
+    case "ipv4":
+      return `${l3Endpoint.address}/32`
+    case "ipv6":
+      return `${l3Endpoint.address}/128`
+    case "hostname":
+      throw new Error("Cannot convert hostname to CIDR")
+  }
+}
+
+/**
+ * Updates the endpoints based on the given mode.
+ *
+ * @param currentEndpoints The current endpoints to update.
+ * @param endpoints The new endpoints to add in string format.
+ * @param inputEndpoints The input endpoints to add in object format.
+ * @param mode The mode to use when updating the endpoints. Can be "replace" or "prepend". Defaults to "prepend".
+ *
+ * @returns The updated list of endpoints.
+ */
+export async function updateEndpoints<TEdnpoints extends network.L34Endpoint>(
+  currentEndpoints: Input<TEdnpoints[]>,
+  endpoints: string[],
+  inputEndpoints: Input<TEdnpoints[]>,
+  mode: ArrayPatchMode = "prepend",
+): Promise<TEdnpoints[]> {
+  const resolvedCurrentEndpoints = await toPromise(currentEndpoints)
+  const resolvedInputEndpoints = await toPromise(inputEndpoints)
+
+  const newEndpoints = uniqueBy(
+    //
+    [...endpoints.map(parseL34Endpoint), ...resolvedInputEndpoints],
+    endpoint => l34EndpointToString(endpoint),
+  )
+
+  if (mode === "replace") {
+    return newEndpoints as TEdnpoints[]
+  }
+
+  return uniqueBy(
+    //
+    [...newEndpoints, ...resolvedCurrentEndpoints],
+    endpoint => l34EndpointToString(endpoint),
+  ) as TEdnpoints[]
+}