@highstate/common 0.14.2 → 0.16.0

package/src/shared/network/ip.ts

@@ -0,0 +1,236 @@
+import type { network } from "@highstate/library"
+
+export type AddressType = network.AddressType
+
+export type ParsedIp = {
+  type: AddressType
+  value: bigint
+}
+
+export type ParsedCidr = {
+  type: AddressType
+  ip: bigint
+  prefixLength: number
+}
+
+export function parseIp(value: string): ParsedIp {
+  if (value.includes(":")) {
+    return { type: "ipv6", value: parseIpv6(value) }
+  }
+
+  return { type: "ipv4", value: parseIpv4(value) }
+}
+
+export function parseCidr(value: string): ParsedCidr {
+  const [ipPart, prefixPart, ...rest] = value.split("/")
+  if (!ipPart || !prefixPart || rest.length > 0) {
+    throw new Error(`Invalid CIDR: "${value}"`)
+  }
+
+  const parsedIp = parseIp(ipPart.trim())
+  const prefix = parseInt(prefixPart.trim(), 10)
+  if (!Number.isFinite(prefix)) {
+    throw new Error(`Invalid CIDR prefix: "${value}"`)
+  }
+
+  const bits = parsedIp.type === "ipv4" ? 32 : 128
+  if (prefix < 0 || prefix > bits) {
+    throw new Error(`Invalid CIDR prefix length: "${value}"`)
+  }
+
+  return { type: parsedIp.type, ip: parsedIp.value, prefixLength: prefix }
+}
+
+export function subnetBaseFromCidr(parsed: ParsedCidr): bigint {
+  const bits = parsed.type === "ipv4" ? 32 : 128
+
+  if (parsed.prefixLength === 0) {
+    return 0n
+  }
+
+  const mask = ((1n << BigInt(parsed.prefixLength)) - 1n) << BigInt(bits - parsed.prefixLength)
+  return parsed.ip & mask
+}
+
+export function cidrBlockSize(type: AddressType, prefixLength: number): bigint {
+  const bits = type === "ipv4" ? 32 : 128
+  return 1n << BigInt(bits - prefixLength)
+}
+
+export function ipToString(type: AddressType, value: bigint): string {
+  return type === "ipv4" ? ipv4ToString(value) : ipv6ToString(value)
+}
+
+function parseIpv4(value: string): bigint {
+  const parts = value.trim().split(".")
+  if (parts.length !== 4) {
+    throw new Error(`Invalid IPv4 address: "${value}"`)
+  }
+
+  let result = 0n
+  for (const part of parts) {
+    if (!part) {
+      throw new Error(`Invalid IPv4 address: "${value}"`)
+    }
+
+    const octet = parseInt(part, 10)
+    if (!Number.isInteger(octet) || octet < 0 || octet > 255) {
+      throw new Error(`Invalid IPv4 address: "${value}"`)
+    }
+
+    result = (result << 8n) + BigInt(octet)
+  }
+
+  return result
+}
+
+function parseIpv6(value: string): bigint {
+  const input = value.trim().toLowerCase()
+  if (!input) {
+    throw new Error(`Invalid IPv6 address: "${value}"`)
+  }
+
+  let leftParts: string[] = []
+  let rightParts: string[] = []
+
+  const doubleColonIndex = input.indexOf("::")
+  if (doubleColonIndex >= 0) {
+    const [left, right] = input.split("::")
+    leftParts = left ? left.split(":") : []
+    rightParts = right ? right.split(":") : []
+  } else {
+    leftParts = input.split(":")
+    rightParts = []
+  }
+
+  const expandIpv4Tail = (parts: string[]): string[] => {
+    if (parts.length === 0) return parts
+    const last = parts.at(-1)!
+    if (!last.includes(".")) {
+      return parts
+    }
+
+    const ipv4Value = parseIpv4(last)
+    const high = Number((ipv4Value >> 16n) & 0xffffn)
+    const low = Number(ipv4Value & 0xffffn)
+
+    return [...parts.slice(0, -1), high.toString(16), low.toString(16)]
+  }
+
+  leftParts = leftParts.filter(p => p.length > 0)
+  rightParts = rightParts.filter(p => p.length > 0)
+
+  leftParts = expandIpv4Tail(leftParts)
+  rightParts = expandIpv4Tail(rightParts)
+
+  const totalParts = leftParts.length + rightParts.length
+  if (doubleColonIndex < 0 && totalParts !== 8) {
+    throw new Error(`Invalid IPv6 address: "${value}"`)
+  }
+  if (totalParts > 8) {
+    throw new Error(`Invalid IPv6 address: "${value}"`)
+  }
+
+  const missing = 8 - totalParts
+  const parts =
+    doubleColonIndex >= 0
+      ? [...leftParts, ...Array.from({ length: missing }, () => "0"), ...rightParts]
+      : leftParts
+
+  if (parts.length !== 8) {
+    throw new Error(`Invalid IPv6 address: "${value}"`)
+  }
+
+  let result = 0n
+  for (const part of parts) {
+    if (!part) {
+      throw new Error(`Invalid IPv6 address: "${value}"`)
+    }
+
+    const hextet = parseInt(part, 16)
+    if (!Number.isInteger(hextet) || hextet < 0 || hextet > 0xffff) {
+      throw new Error(`Invalid IPv6 address: "${value}"`)
+    }
+
+    result = (result << 16n) + BigInt(hextet)
+  }
+
+  return result
+}
+
+function ipv4ToString(value: bigint): string {
+  const parts = [
+    Number((value >> 24n) & 0xffn),
+    Number((value >> 16n) & 0xffn),
+    Number((value >> 8n) & 0xffn),
+    Number(value & 0xffn),
+  ]
+
+  return parts.join(".")
+}
+
+function ipv6ToString(value: bigint): string {
+  const hextets: number[] = []
+  for (let i = 0; i < 8; i++) {
+    const shift = BigInt((7 - i) * 16)
+    hextets.push(Number((value >> shift) & 0xffffn))
+  }
+
+  // Find the longest run of zeros to compress.
+  let bestStart = -1
+  let bestLength = 0
+  let currentStart = -1
+  let currentLength = 0
+
+  for (let i = 0; i < hextets.length; i++) {
+    if (hextets[i] === 0) {
+      if (currentStart === -1) {
+        currentStart = i
+        currentLength = 1
+      } else {
+        currentLength++
+      }
+
+      if (currentLength > bestLength) {
+        bestStart = currentStart
+        bestLength = currentLength
+      }
+    } else {
+      currentStart = -1
+      currentLength = 0
+    }
+  }
+
+  // RFC 5952: only compress runs of 2+ hextets.
+  if (bestLength < 2) {
+    bestStart = -1
+    bestLength = 0
+  }
+
+  const parts: string[] = []
+  for (let i = 0; i < hextets.length; i++) {
+    if (bestStart >= 0 && i >= bestStart && i < bestStart + bestLength) {
+      if (i === bestStart) {
+        parts.push("")
+      }
+      continue
+    }
+
+    parts.push(hextets[i]!.toString(16))
+  }
+
+  let result = parts.join(":")
+  if (bestStart === 0) {
+    result = `:${result}`
+  }
+  if (bestStart >= 0 && bestStart + bestLength === 8) {
+    result = `${result}:`
+  }
+
+  if (result === "") {
+    return "::"
+  }
+
+  // Normalize possible ":::" artifacts into "::".
+  return result.replace(/:{3,}/g, "::")
+}

package/src/shared/network/subnet.spec.ts

@@ -0,0 +1,62 @@
+import { network } from "@highstate/library"
+import { describe, expect, it } from "vitest"
+import { parseAddress } from "./address"
+import { parseSubnet, subnetToString } from "./subnet"
+
+describe("parseSubnet", () => {
+  it("parses an IPv4 CIDR string and canonicalizes the base address", () => {
+    const result = parseSubnet("10.0.0.7/24")
+
+    expect(result.type).toBe("ipv4")
+    expect(result.baseAddress).toBe("10.0.0.0")
+    expect(subnetToString(result)).toBe("10.0.0.0/24")
+    expect(result.prefixLength).toBe(24)
+
+    expect(network.subnetEntity.schema.safeParse(result).success).toBe(true)
+  })
+
+  it("treats an IPv4 address string as a /32 subnet", () => {
+    const result = parseSubnet("10.0.0.7")
+
+    expect(result.type).toBe("ipv4")
+    expect(result.baseAddress).toBe("10.0.0.7")
+    expect(subnetToString(result)).toBe("10.0.0.7/32")
+    expect(result.prefixLength).toBe(32)
+  })
+
+  it("canonicalizes IPv6 subnet strings", () => {
+    const result = parseSubnet("2001:db8:0:0:0:0:0:1/64")
+
+    expect(result.type).toBe("ipv6")
+    expect(result.baseAddress).toBe("2001:db8::")
+    expect(subnetToString(result)).toBe("2001:db8::/64")
+    expect(result.prefixLength).toBe(64)
+  })
+
+  it("treats an IPv6 address string as a /128 subnet", () => {
+    const result = parseSubnet("2001:db8:0:0:0:0:0:1")
+
+    expect(result.type).toBe("ipv6")
+    expect(result.baseAddress).toBe("2001:db8::1")
+    expect(subnetToString(result)).toBe("2001:db8::1/128")
+    expect(result.prefixLength).toBe(128)
+  })
+
+  it("treats an Address entity as a host subnet", () => {
+    const address = parseAddress("10.0.0.7")
+    const result = parseSubnet(address)
+
+    expect(result.type).toBe("ipv4")
+    expect(result.baseAddress).toBe("10.0.0.7")
+    expect(subnetToString(result)).toBe("10.0.0.7/32")
+    expect(result.prefixLength).toBe(32)
+  })
+
+  it("throws on invalid subnet", () => {
+    expect(() => parseSubnet("not-a-cidr")).toThrow(/Invalid/)
+  })
+
+  it("throws on invalid prefix", () => {
+    expect(() => parseSubnet("10.0.0.0/33")).toThrow(/Invalid CIDR prefix length/)
+  })
+})

package/src/shared/network/subnet.ts

@@ -0,0 +1,137 @@
+import { check } from "@highstate/contract"
+import { network } from "@highstate/library"
+import { type InputArray, toPromise } from "@highstate/pulumi"
+import { filter, isNonNullish, map, pipe, uniqueBy } from "remeda"
+import { doesAddressBelongToSubnet } from "./address"
+import { ipToString, type ParsedCidr, parseCidr, parseIp, subnetBaseFromCidr } from "./ip"
+
+export type InputSubnet = network.Subnet | network.Address | string
+
+/**
+ * Parses and normalizes the given subnet string.
+ *
+ * If a Subnet entity is given, it is returned as-is.
+ *
+ * @param subnet The subnet to parse.
+ * @returns The normalized Subnet entity.
+ */
+export function parseSubnet(subnet: InputSubnet): network.Subnet {
+  if (check(network.subnetEntity.schema, subnet)) {
+    return subnet
+  }
+
+  if (check(network.addressEntity.schema, subnet)) {
+    const prefixLength = subnet.type === "ipv4" ? 32 : 128
+
+    const result: network.Subnet = {
+      type: subnet.type,
+      baseAddress: subnet.value,
+      prefixLength,
+    }
+
+    const validated = network.subnetEntity.schema.safeParse(result)
+    if (!validated.success) {
+      throw new Error(
+        `Invalid subnet "${subnet.value}/${prefixLength}": ${validated.error.message}`,
+      )
+    }
+
+    return validated.data
+  }
+
+  const input = subnet.trim()
+  if (!input) {
+    throw new Error("Empty subnet string")
+  }
+
+  let parsed: ParsedCidr
+  if (input.includes("/")) {
+    parsed = parseCidr(input)
+  } else {
+    const ip = parseIp(input)
+    const prefixLength = ip.type === "ipv4" ? 32 : 128
+    parsed = { type: ip.type, ip: ip.value, prefixLength }
+  }
+
+  const subnetBase = subnetBaseFromCidr(parsed)
+  const baseAddress = ipToString(parsed.type, subnetBase)
+
+  const result: network.Subnet = {
+    type: parsed.type,
+    baseAddress,
+    prefixLength: parsed.prefixLength,
+  }
+
+  const validated = network.subnetEntity.schema.safeParse(result)
+  if (!validated.success) {
+    throw new Error(`Invalid subnet "${input}": ${validated.error.message}`)
+  }
+
+  return validated.data
+}
+
+export const privateIpV4Subnets = [
+  parseSubnet("10.0.0.0/8"),
+  parseSubnet("127.0.0.0/8"),
+  parseSubnet("172.16.0.0/12"),
+  parseSubnet("192.168.0.0/16"),
+]
+
+export const privateIpV6Subnets = [
+  parseSubnet("fc00::/7"),
+
+  // IPv4-mapped private ranges.
+  parseSubnet("::ffff:10.0.0.0/104"),
+  parseSubnet("::ffff:127.0.0.0/104"),
+  parseSubnet("::ffff:172.16.0.0/108"),
+  parseSubnet("::ffff:192.168.0.0/112"),
+]
+
+export const privateSubnets = [...privateIpV4Subnets, ...privateIpV6Subnets]
+
+/**
+ * Checks whether the given address is a private address.
+ *
+ * @param address The address to check.
+ * @returns True if the address is private, false otherwise.
+ */
+export function isPrivateAddress(address: network.Address): boolean {
+  for (const subnet of privateSubnets) {
+    if (doesAddressBelongToSubnet(address, subnet)) {
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * Parses multiple subnets from strings and input objects.
+ *
+ * @param subnets The subnet strings to parse.
+ * @param inputSubnets The input subnet objects to use.
+ * @returns The parsed list of subnets objects with duplicates removed.
+ */
+export async function parseSubnets(
+  subnets: (string | undefined | null)[] | null | undefined,
+  inputSubnets: InputArray<network.Subnet | undefined | null> | null | undefined,
+): Promise<network.Subnet[]> {
+  const resolvedInputSubnets = await toPromise(inputSubnets ?? [])
+
+  return pipe(
+    [...(subnets ?? []), ...resolvedInputSubnets],
+    filter(isNonNullish),
+    map(subnet => parseSubnet(subnet)),
+    uniqueBy(subnet => subnetToString(subnet)),
+  )
+}
+
+/**
+ * Converts a subnet to its canonical string representation (CIDR).
+ *
+ * @param subnet The subnet to convert.
+ * @returns The string representation of the subnet.
+ */
+export function subnetToString(subnet: network.Subnet): string {
+  return `${subnet.baseAddress}/${subnet.prefixLength}`
+}

package/src/shared/ssh.ts

@@ -13,7 +13,7 @@ import getKeys, { PrivateExport } from "micro-key-producer/ssh.js"
 import { randomBytes } from "micro-key-producer/utils.js"
 import * as images from "../../assets/images.json"
 import { Command } from "./command"
-import { l3EndpointToL4, l3EndpointToString } from "./network"
+import { l3EndpointToL4, l3EndpointToString } from "./network/endpoints"
 
 export async function createSshTerminal(
   credentials: Input<ssh.Connection>,

package/src/shared/tls.ts

@@ -74,11 +74,11 @@ export class TlsCertificate extends ComponentResource {
     }).apply(async ({ issuers, commonName, dnsNames }) => {
       // for now, we require single issuer to match all requested names
       const matchedIssuer = issuers.find(issuer => {
-        if (commonName && !commonName.endsWith(issuer.domain)) {
+        if (commonName && !issuer.zones.some(zone => commonName.endsWith(zone))) {
           return false
         }
 
-        if (dnsNames && !dnsNames.every(name => name.endsWith(issuer.domain))) {
+        if (dnsNames && !dnsNames.every(name => issuer.zones.some(zone => name.endsWith(zone)))) {
           return false
         }
 
@@ -86,9 +86,25 @@ export class TlsCertificate extends ComponentResource {
       })
 
       if (!matchedIssuer) {
-        throw new Error(
-          `No TLS issuer matched the common name "${commonName}" and DNS names "${dnsNames?.join(", ") ?? ""}"`,
-        )
+        if (commonName && dnsNames && dnsNames.length > 0) {
+          const dnsNameList = dnsNames.join(", ")
+
+          throw new Error(
+            `No TLS issuer matched the common name "${commonName}" and DNS names "${dnsNameList}"`,
+          )
+        }
+
+        if (commonName) {
+          throw new Error(`No TLS issuer matched the common name "${commonName}"`)
+        }
+
+        if (dnsNames && dnsNames.length > 0) {
+          const dnsNameList = dnsNames.join(", ")
+
+          throw new Error(`No TLS issuer matched the DNS names "${dnsNameList}"`)
+        }
+
+        throw new Error("No TLS issuer provided")
       }
 
       return await tlsCertificateMediator.call(matchedIssuer.implRef, {

package/src/shared/utils.ts

@@ -0,0 +1,93 @@
+import type { Metadata, MetadataContainer } from "@highstate/library"
+import { compile } from "filter-expression"
+
+/**
+ * Filter a list of items using a filter expression.
+ *
+ * See [filter-expression](https://github.com/tronghieu/filter-expression?tab=readme-ov-file#language) for more details on the expression syntax.
+ *
+ * @param items The items to filter.
+ * @param expression The filter expression.
+ * @param getContext The function to get the context for each item. Defaults to the item itself.
+ * @returns The filtered items.
+ */
+export function filterByExpression<T>(
+  items: T[],
+  expression: string,
+  getContext = (item: T) => item as Record<string, unknown>,
+): T[] {
+  const { evaluate } = compile(expression)
+
+  return items.filter(item => evaluate(getContext(item)))
+}
+
+/**
+ * Filter a list of items with metadata using a filter expression.
+ *
+ * See `filterByExpression` for more details.
+ *
+ * @param items The items to filter.
+ * @param expression The filter expression.
+ * @param getContext The function to get the context for each item. Defaults to the item itself.
+ * @returns The filtered items.
+ */
+export function filterWithMetadataByExpression<T extends MetadataContainer>(
+  items: T[],
+  expression: string,
+  getContext = (item: T) => item as Record<string, unknown>,
+): T[] {
+  return filterByExpression(items, expression, item =>
+    getContext({ ...item, metadata: item.metadata ? flattenMetadata(item.metadata) : undefined }),
+  )
+}
+
+/**
+ * Transforms each dot-separated key in the metadata into a nested object structure.
+ *
+ * Should be used to create valid context for `filterByExpression`.
+ *
+ * Example:
+ *
+ * ```ts
+ * const metadata = {
+ *   "k8s.service": {}
+ * }
+ * ```
+ *
+ * becomes
+ *
+ * ```ts
+ * const flattened = {
+ *   k8s: {
+ *     service: {}
+ *   }
+ * }
+ * ```
+ *
+ * @param metadata The metadata to flatten.
+ * @returns The flattened metadata.
+ */
+export function flattenMetadata(metadata: Metadata): Record<string, unknown> {
+  const result = {}
+
+  for (const [key, value] of Object.entries(metadata)) {
+    const path = key.split(".")
+    // biome-ignore lint/suspicious/noExplicitAny: to simplify implementation
+    let current: any = result
+
+    for (let i = 0; i < path.length; i++) {
+      const segment = path[i]
+
+      if (i === path.length - 1) {
+        current[segment] = value
+      } else {
+        if (!(segment in current)) {
+          current[segment] = {}
+        }
+        current = current[segment] as Record<string, unknown>
+      }
+    }
+  }
+
+  return result
+}

package/src/units/databases/etcd-patch/index.ts

@@ -0,0 +1,23 @@
+import { databases } from "@highstate/library"
+import { forUnit, toPromise } from "@highstate/pulumi"
+import { l4EndpointToString, parseEndpoints } from "../../../shared"
+
+const { args, inputs, outputs } = forUnit(databases.etcdPatch)
+
+const resolvedInputEndpoints = await toPromise(inputs.endpoints ?? [])
+
+const shouldOverrideEndpoints =
+  args.endpoints.length > 0 || resolvedInputEndpoints.some(endpoint => endpoint != null)
+const endpoints = shouldOverrideEndpoints
+  ? await parseEndpoints(args.endpoints, inputs.endpoints, 4)
+  : await parseEndpoints([], inputs.endpoints, 4)
+
+export default outputs({
+  etcd: {
+    endpoints,
+  },
+
+  $statusFields: {
+    endpoints: endpoints.map(l4EndpointToString),
+  },
+})

package/src/units/databases/existing-etcd/index.ts

@@ -0,0 +1,11 @@
+import { databases } from "@highstate/library"
+import { forUnit } from "@highstate/pulumi"
+import { parseEndpoints } from "../../../shared"
+
+const { args, inputs, outputs } = forUnit(databases.existingEtcd)
+
+export default outputs({
+  etcd: {
+    endpoints: parseEndpoints(args.endpoints, inputs.endpoints, 4),
+  },
+})

package/src/units/databases/existing-mariadb/index.ts

@@ -6,7 +6,7 @@ const { args, secrets, inputs, outputs } = forUnit(databases.existingMariadb)
 
 export default outputs({
   mariadb: {
-    endpoints: parseEndpoints(args.endpoints, inputs.endpoints),
+    endpoints: parseEndpoints(args.endpoints, inputs.endpoints, 4),
     username: args.username,
     password: secrets.password,
     database: args.database,

package/src/units/databases/existing-mongodb/index.ts

@@ -6,7 +6,7 @@ const { args, secrets, inputs, outputs } = forUnit(databases.existingMongodb)
 
 export default outputs({
   mongodb: {
-    endpoints: parseEndpoints(args.endpoints, inputs.endpoints),
+    endpoints: parseEndpoints(args.endpoints, inputs.endpoints, 4),
     username: args.username,
     password: secrets.password,
     database: args.database,

package/src/units/databases/existing-postgresql/index.ts

@@ -6,7 +6,7 @@ const { args, secrets, inputs, outputs } = forUnit(databases.existingPostgresql)
 
 export default outputs({
   postgresql: {
-    endpoints: parseEndpoints(args.endpoints, inputs.endpoints),
+    endpoints: parseEndpoints(args.endpoints, inputs.endpoints, 4),
     username: args.username,
     password: secrets.password,
     database: args.database,

package/src/units/databases/existing-redis/index.ts

@@ -12,7 +12,7 @@ if (redisDatabase !== undefined && Number.isNaN(redisDatabase)) {
 
 export default outputs({
   redis: {
-    endpoints: parseEndpoints(args.endpoints, inputs.endpoints),
+    endpoints: parseEndpoints(args.endpoints, inputs.endpoints, 4),
     database: redisDatabase ?? 0,
   },
 })

package/src/units/databases/existing-s3/index.ts

@@ -6,7 +6,7 @@ const { args, secrets, inputs, outputs } = forUnit(databases.existingS3)
 
 export default outputs({
   s3: {
-    endpoints: parseEndpoints(args.endpoints, inputs.endpoints),
+    endpoints: parseEndpoints(args.endpoints, inputs.endpoints, 4),
     region: args.region,
     accessKey: args.accessKey,
     secretKey: secrets.secretKey,

package/src/units/databases/mariadb-patch/index.ts

@@ -0,0 +1,27 @@
+import { databases } from "@highstate/library"
+import { forUnit, toPromise } from "@highstate/pulumi"
+import { l4EndpointToString, parseEndpoints } from "../../../shared"
+
+const { args, inputs, outputs } = forUnit(databases.mariadbPatch)
+
+const mariadb = await toPromise(inputs.mariadb)
+const resolvedInputEndpoints = await toPromise(inputs.endpoints ?? [])
+
+const shouldOverrideEndpoints =
+  args.endpoints.length > 0 || resolvedInputEndpoints.some(endpoint => endpoint != null)
+const endpoints = shouldOverrideEndpoints
+  ? await parseEndpoints(args.endpoints, inputs.endpoints, 4)
+  : mariadb.endpoints
+
+export default outputs({
+  mariadb: {
+    ...mariadb,
+    endpoints,
+    username: args.username ?? mariadb.username,
+    database: args.database ?? mariadb.database,
+  },
+
+  $statusFields: {
+    endpoints: endpoints.map(l4EndpointToString),
+  },
+})