@highstate/common 0.14.2 → 0.16.0

package/src/shared/network/address-space.ts

@@ -0,0 +1,364 @@
+import { check } from "@highstate/contract"
+import { network } from "@highstate/library"
+import { addressToCidr } from "./address"
+import { cidrBlockSize, ipToString, parseCidr, parseIp, subnetBaseFromCidr } from "./ip"
+import { subnetToString } from "./subnet"
+
+export type AddressSpaceArgs = {
+  /**
+   * The list of addresses to include in the address space.
+   *
+   * Supports:
+   * - Other address space entities;
+   * - Address entities;
+   * - Subnet entities;
+   * - L3 endpoint entities;
+   * - String representations of addresses, subnets, or ranges.
+   *
+   * The supported formats for strings are:
+   * - Single IP address (e.g., `192.168.1.1`);
+   * - CIDR notation (e.g., `192.168.1.1/24`);
+   * - Dash notation (e.g., `192.168.1.1-192.168.1.254`).
+   *
+   * The addresses can be a mix of IPv4 and IPv6.
+   */
+  included: InputAddressSpace[]
+
+  /**
+   * The list of addresses to exclude from the `addresses` list.
+   *
+   * The supported formats are the same as in `addresses`.
+   */
+  excluded?: InputAddressSpace[]
+}
+
+export type InputAddressSpace =
+  | network.AddressSpace
+  | network.Address
+  | network.Subnet
+  | network.L3Endpoint
+  | string
+
+type IpFamily = network.AddressType
+
+type IpRange = {
+  family: IpFamily
+  start: bigint
+  endExclusive: bigint
+}
+
+/**
+ * Creates an address space from a list of addresses/subnets/ranges.
+ *
+ * @param included The list of addresses to include in the address space.
+ * @param excluded The list of addresses to exclude from the `included` list.
+ * @returns The created address space entity.
+ */
+export function createAddressSpace({
+  included,
+  excluded = [],
+}: AddressSpaceArgs): network.AddressSpace {
+  const includedRanges = included.flatMap(resolveInputToRanges)
+  const excludedRanges = excluded.flatMap(resolveInputToRanges)
+
+  const normalized = normalizeRanges(includedRanges, excludedRanges)
+  const subnets = rangesToCanonicalSubnets(normalized)
+
+  return { subnets }
+}
+
+function resolveInputToRanges(input: InputAddressSpace): IpRange[] {
+  if (typeof input === "string") {
+    return [rangeFromString(input)]
+  }
+
+  if (check(network.addressSpaceEntity.schema, input)) {
+    return input.subnets.flatMap(subnet => [rangeFromCidr(subnetToString(subnet))])
+  }
+
+  if (check(network.subnetEntity.schema, input)) {
+    return [rangeFromCidr(subnetToString(input))]
+  }
+
+  if (check(network.addressEntity.schema, input)) {
+    return [rangeFromCidr(addressToCidr(input))]
+  }
+
+  if (check(network.l3EndpointEntity.schema, input)) {
+    if (input.type === "hostname") {
+      return []
+    }
+
+    const cidr = (input as unknown as { cidr?: unknown }).cidr
+    if (typeof cidr === "string") {
+      return [rangeFromCidr(cidr)]
+    }
+
+    const address = (input as unknown as { address?: unknown }).address
+    if (typeof address === "string") {
+      const parsed = parseIp(address)
+      const prefixLength = parsed.type === "ipv4" ? 32 : 128
+      return [
+        rangeFromParsedCidr({ family: parsed.type, base: parsed.value, prefix: prefixLength }),
+      ]
+    }
+
+    if (check(network.addressEntity.schema, address)) {
+      return [rangeFromCidr(addressToCidr(address))]
+    }
+
+    throw new Error("Invalid L3 endpoint: missing address information")
+  }
+
+  throw new Error("Unsupported address space input")
+}
+
+function rangeFromString(value: string): IpRange {
+  const trimmed = value.trim()
+  if (!trimmed) {
+    throw new Error("Empty address string")
+  }
+
+  if (trimmed.includes("-")) {
+    const [left, right, ...rest] = trimmed.split("-")
+    if (!left || !right || rest.length > 0) {
+      throw new Error(`Invalid range: "${value}"`)
+    }
+
+    const start = parseIp(left.trim())
+    const end = parseIp(right.trim())
+
+    if (start.type !== end.type) {
+      throw new Error(`Range must not mix IPv4 and IPv6: "${value}"`)
+    }
+
+    const min = start.value <= end.value ? start.value : end.value
+    const max = start.value <= end.value ? end.value : start.value
+
+    return {
+      family: start.type,
+      start: min,
+      endExclusive: max + 1n,
+    }
+  }
+
+  if (trimmed.includes("/")) {
+    return rangeFromCidr(trimmed)
+  }
+
+  const parsed = parseIp(trimmed)
+  return {
+    family: parsed.type,
+    start: parsed.value,
+    endExclusive: parsed.value + 1n,
+  }
+}
+
+function rangeFromCidr(cidr: string): IpRange {
+  const parsed = parseCidr(cidr)
+  return rangeFromParsedCidr({
+    family: parsed.type,
+    base: subnetBaseFromCidr(parsed),
+    prefix: parsed.prefixLength,
+  })
+}
+
+function rangeFromParsedCidr(parsed: { family: IpFamily; base: bigint; prefix: number }): IpRange {
+  const size = cidrBlockSize(parsed.family, parsed.prefix)
+
+  return {
+    family: parsed.family,
+    start: parsed.base,
+    endExclusive: parsed.base + size,
+  }
+}
+
+function normalizeRanges(included: IpRange[], excluded: IpRange[]): IpRange[] {
+  const includedByFamily = splitByFamily(included)
+  const excludedByFamily = splitByFamily(excluded)
+
+  const normalizedV4 = subtractMergedRanges(
+    mergeRanges(includedByFamily.v4),
+    mergeRanges(excludedByFamily.v4),
+  )
+  const normalizedV6 = subtractMergedRanges(
+    mergeRanges(includedByFamily.v6),
+    mergeRanges(excludedByFamily.v6),
+  )
+
+  return [...normalizedV4, ...normalizedV6]
+}
+
+function splitByFamily(ranges: IpRange[]): { v4: IpRange[]; v6: IpRange[] } {
+  const v4: IpRange[] = []
+  const v6: IpRange[] = []
+
+  for (const range of ranges) {
+    if (range.start >= range.endExclusive) continue
+
+    if (range.family === "ipv4") {
+      v4.push(range)
+    } else {
+      v6.push(range)
+    }
+  }
+
+  return { v4, v6 }
+}
+
+function mergeRanges(ranges: IpRange[]): IpRange[] {
+  const sorted = [...ranges].sort((a, b) => {
+    if (a.start === b.start) {
+      return a.endExclusive < b.endExclusive ? -1 : a.endExclusive > b.endExclusive ? 1 : 0
+    }
+    return a.start < b.start ? -1 : 1
+  })
+
+  const merged: IpRange[] = []
+
+  for (const current of sorted) {
+    const last = merged.at(-1)
+    if (!last) {
+      merged.push({ ...current })
+      continue
+    }
+
+    if (current.start <= last.endExclusive) {
+      if (current.endExclusive > last.endExclusive) {
+        last.endExclusive = current.endExclusive
+      }
+      continue
+    }
+
+    merged.push({ ...current })
+  }
+
+  return merged
+}
+
+function subtractMergedRanges(included: IpRange[], excluded: IpRange[]): IpRange[] {
+  if (included.length === 0) return []
+  if (excluded.length === 0) return included
+
+  const result: IpRange[] = []
+  let j = 0
+
+  for (const incOriginal of included) {
+    const inc: IpRange = { ...incOriginal }
+
+    while (j < excluded.length && excluded[j]!.endExclusive <= inc.start) {
+      j++
+    }
+
+    while (j < excluded.length) {
+      const exc = excluded[j]!
+
+      if (exc.start >= inc.endExclusive) {
+        break
+      }
+
+      if (exc.start <= inc.start) {
+        inc.start = inc.start < exc.endExclusive ? exc.endExclusive : inc.start
+        if (inc.start >= inc.endExclusive) {
+          break
+        }
+
+        if (exc.endExclusive <= inc.start) {
+          j++
+        }
+        continue
+      }
+
+      result.push({
+        family: inc.family,
+        start: inc.start,
+        endExclusive: exc.start,
+      })
+
+      inc.start = exc.endExclusive
+      if (inc.start >= inc.endExclusive) {
+        break
+      }
+    }
+
+    if (inc.start < inc.endExclusive) {
+      result.push(inc)
+    }
+  }
+
+  return result
+}
+
+function rangesToCanonicalSubnets(ranges: IpRange[]): network.Subnet[] {
+  const subnets: network.Subnet[] = []
+
+  for (const range of ranges) {
+    for (const cidr of rangeToCidrs(range)) {
+      const baseAddress = ipToString(cidr.family, cidr.base)
+
+      subnets.push({
+        type: cidr.family,
+        baseAddress,
+        prefixLength: cidr.prefix,
+      })
+    }
+  }
+
+  return sortSubnetsCanonical(subnets)
+}
+
+function sortSubnetsCanonical(subnets: network.Subnet[]): network.Subnet[] {
+  return [...subnets].sort((a, b) => {
+    const aFamily = a.type
+    const bFamily = b.type
+    if (aFamily !== bFamily) {
+      return aFamily === "ipv4" ? -1 : 1
+    }
+
+    const aBase = parseIp(a.baseAddress).value
+    const bBase = parseIp(b.baseAddress).value
+
+    if (aBase !== bBase) {
+      return aBase < bBase ? -1 : 1
+    }
+
+    return a.prefixLength - b.prefixLength
+  })
+}
+
+function rangeToCidrs(range: IpRange): Array<{ family: IpFamily; base: bigint; prefix: number }> {
+  const bits = range.family === "ipv4" ? 32 : 128
+  const result: Array<{ family: IpFamily; base: bigint; prefix: number }> = []
+
+  let current = range.start
+  while (current < range.endExclusive) {
+    const remaining = range.endExclusive - current
+    const maxAligned = current === 0n ? 1n << BigInt(bits) : current & -current
+    const maxByRemaining = highestPowerOfTwoAtMost(remaining)
+
+    const blockSize = maxAligned < maxByRemaining ? maxAligned : maxByRemaining
+    const prefix = bits - bitLength(blockSize) + 1
+
+    result.push({
+      family: range.family,
+      base: current,
+      prefix,
+    })
+
+    current += blockSize
+  }
+
+  return result
+}
+
+function highestPowerOfTwoAtMost(value: bigint): bigint {
+  if (value <= 0n) {
+    throw new Error("Value must be positive")
+  }
+
+  return 1n << BigInt(bitLength(value) - 1)
+}
+
+function bitLength(value: bigint): number {
+  return value.toString(2).length
+}

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

@@ -0,0 +1,109 @@
+import { network } from "@highstate/library"
+import { describe, expect, it } from "vitest"
+import { addressToCidr, doesAddressBelongToSubnet, mergeAddresses, parseAddress } from "./address"
+import { subnetToString } from "./subnet"
+
+describe("parseAddress", () => {
+  it("parses an IPv4 address string", () => {
+    const result = parseAddress("10.0.0.1")
+
+    expect(result.type).toBe("ipv4")
+    expect(result.value).toBe("10.0.0.1")
+    expect(addressToCidr(result)).toBe("10.0.0.1/32")
+    expect(subnetToString(result.subnet)).toBe("10.0.0.1/32")
+    expect(result.subnet.prefixLength).toBe(32)
+
+    expect(network.addressEntity.schema.safeParse(result).success).toBe(true)
+  })
+
+  it("parses an IPv4 CIDR string as address/prefix", () => {
+    const result = parseAddress("10.0.0.7/24")
+
+    expect(result.type).toBe("ipv4")
+    expect(result.value).toBe("10.0.0.7")
+    expect(addressToCidr(result)).toBe("10.0.0.7/24")
+    expect(subnetToString(result.subnet)).toBe("10.0.0.0/24")
+    expect(result.subnet.baseAddress).toBe("10.0.0.0")
+    expect(result.subnet.prefixLength).toBe(24)
+  })
+
+  it("canonicalizes IPv6 address strings", () => {
+    const result = parseAddress("2001:db8:0:0:0:0:0:1")
+
+    expect(result.type).toBe("ipv6")
+    expect(result.value).toBe("2001:db8::1")
+    expect(addressToCidr(result)).toBe("2001:db8::1/128")
+    expect(subnetToString(result.subnet)).toBe("2001:db8::1/128")
+    expect(result.subnet.prefixLength).toBe(128)
+  })
+
+  it("throws on invalid address", () => {
+    expect(() => parseAddress("not-an-ip")).toThrow(/Invalid/)
+  })
+
+  it("throws on invalid prefix", () => {
+    expect(() => parseAddress("10.0.0.1/33")).toThrow(/Invalid CIDR prefix length/)
+  })
+})
+
+describe("doesAddressBelongToSubnet", () => {
+  it("returns true when an IPv4 address belongs to the subnet", () => {
+    const address = parseAddress("10.0.0.5")
+    const subnet = parseAddress("10.0.0.0/24").subnet
+
+    expect(doesAddressBelongToSubnet(address, subnet)).toBe(true)
+  })
+
+  it("returns false when an IPv4 address does not belong to the subnet", () => {
+    const address = parseAddress("10.0.1.5")
+    const subnet = parseAddress("10.0.0.0/24").subnet
+
+    expect(doesAddressBelongToSubnet(address, subnet)).toBe(false)
+  })
+
+  it("treats /0 as containing every address", () => {
+    const address = parseAddress("10.123.45.67")
+    const subnet = parseAddress("0.0.0.0/0").subnet
+
+    expect(doesAddressBelongToSubnet(address, subnet)).toBe(true)
+  })
+
+  it("returns true when an IPv6 address belongs to the subnet", () => {
+    const address = parseAddress("2001:db8::1")
+    const subnet = parseAddress("2001:db8::/64").subnet
+
+    expect(doesAddressBelongToSubnet(address, subnet)).toBe(true)
+  })
+
+  it("returns false when an IPv6 address does not belong to the subnet", () => {
+    const address = parseAddress("2001:db9::1")
+    const subnet = parseAddress("2001:db8::/64").subnet
+
+    expect(doesAddressBelongToSubnet(address, subnet)).toBe(false)
+  })
+
+  it("returns false for mismatched address and subnet types", () => {
+    const address = parseAddress("10.0.0.1")
+    const ipv6Subnet = parseAddress("2001:db8::/64").subnet
+
+    expect(doesAddressBelongToSubnet(address, ipv6Subnet)).toBe(false)
+  })
+})
+
+describe("mergeAddresses", () => {
+  it("dedupes by cidr", () => {
+    const a = parseAddress("10.0.0.1")
+    const b = parseAddress("10.0.0.1")
+
+    expect(mergeAddresses([a, b])).toEqual([b])
+  })
+
+  it("keeps stable order of last occurrences", () => {
+    const a1 = parseAddress("10.0.0.1")
+    const b1 = parseAddress("10.0.0.2")
+    const a2 = parseAddress("10.0.0.1")
+    const c1 = parseAddress("10.0.0.3")
+
+    expect(mergeAddresses([a1, b1, a2, c1])).toEqual([a2, b1, c1])
+  })
+})

package/src/shared/network/address.ts

@@ -0,0 +1,119 @@
+import { check } from "@highstate/contract"
+import { network } from "@highstate/library"
+import { ipToString, parseCidr, parseIp, subnetBaseFromCidr } from "./ip"
+
+export type InputAddress = network.Address | string
+
+/**
+ * Parses and normalizes the given address string.
+ * If Address entity is given, it is returned as-is.
+ *
+ * @param address The address to parse.
+ * @returns The normalized Address entity.
+ */
+export function parseAddress(address: InputAddress): network.Address {
+  if (check(network.addressEntity.schema, address)) {
+    return address
+  }
+
+  const input = address.trim()
+  if (!input) {
+    throw new Error("Empty address string")
+  }
+
+  const parsed = input.includes("/") ? parseCidr(input) : parseCidrFromIp(input)
+  const canonicalAddress = ipToString(parsed.type, parsed.ip)
+
+  const subnetBase = subnetBaseFromCidr(parsed)
+  const subnetBaseAddress = ipToString(parsed.type, subnetBase)
+
+  const result: network.Address = {
+    type: parsed.type,
+    value: canonicalAddress,
+    subnet: {
+      type: parsed.type,
+      baseAddress: subnetBaseAddress,
+      prefixLength: parsed.prefixLength,
+    },
+  }
+
+  const validated = network.addressEntity.schema.safeParse(result)
+  if (!validated.success) {
+    throw new Error(`Invalid address "${input}": ${validated.error.message}`)
+  }
+
+  return validated.data
+}
+
+/**
+ * Converts an address entity to its full CIDR string representation.
+ *
+ * The result format is `<address>/<prefix-length>`.
+ *
+ * @param address The address entity.
+ * @returns The CIDR string representation.
+ */
+export function addressToCidr(address: network.Address): string {
+  return `${address.value}/${address.subnet.prefixLength}`
+}
+
+/**
+ * Checks whether the given address belongs to the specified subnet.
+ *
+ * @param address The address to check.
+ * @param subnet The subnet to check against.
+ * @returns True if the address belongs to the subnet, false otherwise.
+ */
+export function doesAddressBelongToSubnet(
+  address: network.Address,
+  subnet: network.Subnet,
+): boolean {
+  if (address.type !== subnet.type) {
+    return false
+  }
+
+  const addressIp = parseIp(address.value)
+  const subnetBaseIp = parseIp(subnet.baseAddress)
+
+  if (addressIp.type !== subnet.type || subnetBaseIp.type !== subnet.type) {
+    return false
+  }
+
+  const bits = subnet.type === "ipv4" ? 32 : 128
+  if (subnet.prefixLength === 0) {
+    return true
+  }
+
+  const mask = ((1n << BigInt(subnet.prefixLength)) - 1n) << BigInt(bits - subnet.prefixLength)
+
+  return (addressIp.value & mask) === (subnetBaseIp.value & mask)
+}
+
+/**
+ * Merges duplicate addresses by their canonical CIDR key.
+ *
+ * If multiple addresses share the same `cidr`, the last one wins.
+ *
+ * @param addresses The list of addresses to merge.
+ * @returns The merged list of addresses with duplicates removed.
+ */
+export function mergeAddresses(addresses: network.Address[]): network.Address[] {
+  const mergedMap = new Map<string, network.Address>()
+
+  for (const address of addresses) {
+    mergedMap.set(addressToCidr(address), address)
+  }
+
+  return Array.from(mergedMap.values())
+}
+
+function parseCidrFromIp(value: string) {
+  const parsed = parseIp(value)
+  const prefixLength = parsed.type === "ipv4" ? 32 : 128
+
+  return {
+    type: parsed.type,
+    ip: parsed.value,
+    prefixLength,
+  }
+}