@k8ts/instruments 0.11.3 → 0.12.0

package/src/expressions/network/ip/ip4.ts

@@ -0,0 +1,14 @@
+import { Address4 } from "ip-address"
+
+// TODO: Validate IP and Subnet strings more thoroughly
+// TODO: Consider wrapping an existing library or just exposing that library directly
+// TODO: Add IPv6 support
+
+export type Ip4_Input_String = `${number}.${number}.${number}.${number}`
+
+export class Ip4<Text extends Ip4_Input_String = Ip4_Input_String> {
+    readonly _addr4: Address4 | undefined
+    constructor(readonly text: Text) {
+        this._addr4 = new Address4(text)
+    }
+}

package/src/expressions/network/ip/subnet4.ts

@@ -0,0 +1,9 @@
+import { Address4 } from "ip-address"
+
+export type Subnet4_Input_String = `${number}.${number}.${number}.${number}/${number}`
+export class Subnet4<Text extends Subnet4_Input_String = Subnet4_Input_String> {
+    readonly _addr4: Address4 | undefined
+    constructor(readonly text: Text) {
+        this._addr4 = new Address4(text)
+    }
+}

package/src/expressions/network/ports/entry.ts

@@ -0,0 +1,44 @@
+import { mapValues } from "lodash"
+import { Ip4 } from "../ip/ip4"
+import { parsePortSpec } from "./parser"
+import { PortExports } from "./provider"
+import type {
+    Port_Full,
+    Port_Input,
+    Port_Input_Object,
+    Port_Protocol,
+    PortExports_Input
+} from "./types"
+
+function portSetEntry(name: string, value: Port_Input_Object): Port_Full {
+    const proto = value.protocol ? (value.protocol.toUpperCase() as Port_Protocol) : "TCP"
+    return {
+        name,
+        port: value.port,
+        protocol: proto,
+        hostIp: value.hostIp ? new Ip4(value.hostIp) : undefined,
+        hostPort: value.hostPort
+    }
+}
+
+export function parsePortInput(name: string, input: Port_Input): Port_Full {
+    if (typeof input === "string") {
+        return portSetEntry(name, parsePortSpec(name, input))
+    }
+    if (typeof input === "number") {
+        return portSetEntry(name, {
+            port: input,
+            protocol: "TCP" as const
+        })
+    }
+    return portSetEntry(name, input)
+}
+
+export function portRecordInput(
+    record: PortExports_Input<string> | PortExports<string>
+): Record<string, Port_Full> {
+    if ("record" in record) {
+        return record.record as any
+    }
+    return mapValues(record, (v, k) => parsePortInput(k, v))
+}

package/src/expressions/network/ports/mapping.ts

@@ -0,0 +1,108 @@
+import { mapValues, pickBy } from "lodash"
+import { display } from "../../../utils/mixin/display"
+import { K8tsNetworkError } from "../error"
+import type { PortMap_Item } from "./types"
+
+/**
+ * Represents an immutable mapping of named ports to their frontend/backend configuration.
+ *
+ * Used to define how container ports are exposed through services, mapping backend container ports
+ * to frontend service ports.
+ *
+ * @template Names The union type of all port names in the map.
+ */
+export interface PortMap<Names extends string> {
+    /**
+     * Creates a new PortMap containing only the specified port names.
+     *
+     * @param name The port names to include in the new map.
+     * @returns A new PortMap with only the selected ports.
+     */
+    pick<InNames extends Names>(...name: InNames[]): PortMap<InNames>
+
+    /** The underlying map of port names to their mapping entries. */
+    get values(): Record<string, PortMap_Item>
+
+    /**
+     * Remaps the frontend ports to new values.
+     *
+     * @param mapping A record mapping port names to their new frontend port numbers.
+     * @returns A new PortMap with updated frontend ports.
+     */
+    map(mapping: Record<Names, number>): PortMap<Names>
+
+    /**
+     * Retrieves a port mapping entry by name.
+     *
+     * @param name The name of the port to retrieve.
+     * @returns The port mapping entry.
+     * @throws {K8tsNetworkError} If the port name is not found in the map.
+     */
+    get(name: Names): PortMap_Item
+
+    /** Converts this PortMap to a standard Map. */
+    toMap(): Record<string, PortMap_Item>
+}
+
+export function PortMap<Names extends string>(map: Record<string, PortMap_Item>) {
+    return new _PortMap(map) as any as PortMap<Names>
+}
+
+@display({
+    simple(self) {
+        return `PortMap(${Object.keys(self._map).join(", ")})`
+    }
+})
+class _PortMap {
+    constructor(readonly _map: Record<string, PortMap_Item>) {}
+
+    private _apply(
+        f: (map: Record<string, PortMap_Item>) => Record<string, PortMap_Item>
+    ): _PortMap {
+        return new _PortMap(f(this._map))
+    }
+
+    pick(...name: string[]): _PortMap {
+        return this._apply(map => pickBy(map, (_, key) => name.includes(key)))
+    }
+
+    get values() {
+        return this._map
+    }
+
+    map(mapping: Record<string, number>): _PortMap {
+        return new _PortMap(
+            mapValues(this._map, entry => {
+                return {
+                    ...entry,
+                    frontend: mapping[entry.name]
+                }
+            })
+        )
+    }
+
+    get(name: string): PortMap_Item {
+        if (!(name in this._map)) {
+            throw new K8tsNetworkError(`Port ${name} not found`)
+        }
+        return this._map[name] as PortMap_Item
+    }
+
+    toMap() {
+        return this._map
+    }
+}
+
+/**
+ * Input type for creating port mappings.
+ *
+ * Each port name maps to either:
+ *
+ * - A number specifying the frontend port
+ * - `true` to use the same port number as the backend
+ *
+ * @template Names The union type of port names.
+ */
+export type PortMapping_Input<Names extends string = string> = {
+    [K in Names]: number | true
+}

package/src/expressions/network/ports/{tools/parse.ts → parser.ts}

@@ -1,7 +1,7 @@
 import { anyStringOf, int, string } from "parjs"
 import { map, maybe, must, qthen, then } from "parjs/combinators"
-import { PortError } from "../error"
-import type { Port_Full_Input, Port_Protocol } from "../types"
+import { K8tsNetworkError } from "../error"
+import type { Port_Input_Object, Port_Protocol } from "./types"
 
 function validatePort(port: number) {
     if (port < 0 || port > 65535) {
@@ -25,7 +25,7 @@ const pPortSpec = pPort.pipe(
         return {
             port,
             protocol: protocol?.toUpperCase() ?? "TCP"
-        } as Port_Full_Input
+        } as Port_Input_Object
     })
 )
 
@@ -34,7 +34,7 @@ export function parsePortSpec(name: string, input: string) {
     if (result.kind === "OK") {
         return result.value
     }
-    throw new PortError(name, {
+    throw new K8tsNetworkError(name, {
         parseError: result.reason
     })
 }

package/src/expressions/network/ports/provider.ts

@@ -0,0 +1,193 @@
+import { mapValues, pick } from "lodash"
+import { display } from "../../../utils/mixin/display"
+import { K8tsNetworkError } from "../error"
+import { parsePortInput, portRecordInput } from "./entry"
+import { PortMap, PortMapping_Input } from "./mapping"
+import type {
+    Port_Full,
+    Port_Input_Object,
+    Port_Input_Protocol,
+    Port_Input_Scalar,
+    PortExports_Input
+} from "./types"
+
+/**
+ * An immutable dictionary of named network ports exported by a container. Each port also has an
+ * attached configuration.
+ *
+ * @template Names All exported port names.
+ */
+export interface PortExports<Names extends string = never> {
+    /**
+     * Creates a new PortExports that is the union of this and another PortExports.
+     *
+     * @param other The other PortExports to merge with.
+     * @returns A new PortExports containing ports from both dictionaries. The 2nd dictionary's
+     *   ports will overwrite any with the same name from the first.
+     */
+    union<InNames extends string>(other: PortExports<InNames>): PortExports<Names | InNames>
+
+    /**
+     * Adds a port with explicit name, port number, and protocol.
+     *
+     * @param name The unique name for the port.
+     * @param port The port number.
+     * @param protocol The protocol (TCP or UDP).
+     */
+    add<Name extends string>(
+        name: Name,
+        port: Port_Input_Scalar,
+        protocol: Port_Input_Protocol
+    ): PortExports<Names | Name>
+    /**
+     * Adds a port with a name and full port configuration.
+     *
+     * @param name The unique name for the port.
+     * @param entry The port configuration including number and protocol, and optional host
+     *   settings.
+     */
+    add<Name extends string>(name: Name, entry: Port_Input_Object): PortExports<Names | Name>
+    /**
+     * Adds multiple ports from a record of port configurations.
+     *
+     * @param input A record mapping port names to their configurations.
+     */
+    add<InNames extends string>(input?: PortExports_Input<InNames>): PortExports<Names | InNames>
+
+    /**
+     * Creates a new PortExports containing only the specified port names.
+     *
+     * @param name The port names to include.
+     * @returns A new PortExports with only the selected ports.
+     */
+    pick<InNames extends Names>(...name: InNames[]): PortExports<InNames>
+
+    /** An array of all port names in this set. */
+    get names(): Names[]
+
+    /**
+     * Retrieves a port by name.
+     *
+     * @param name The name of the port to retrieve.
+     * @returns The full port configuration.
+     * @throws {K8tsNetworkError} If the port name is not found.
+     */
+    get(name: Names): Port_Full
+
+    /** The underlying map of port names to their full configurations. */
+    get values(): Port_Full[]
+
+    get record(): Record<Names, Port_Full>
+
+    /**
+     * Creates a PortMap by mapping each port to a frontend port number.
+     *
+     * @param mapping A record where each port name maps to either a frontend port number or `true`
+     *   to use the backend port.
+     * @returns A new PortMap with the specified frontend mappings.
+     * @throws {K8tsNetworkError} If a port name is missing from the mapping or has an invalid
+     *   value.
+     */
+    map(mapping: PortMapping_Input<Names>): PortMap<Names>
+}
+
+export function PortExports<Names extends string = never>(
+    record: PortExports_Input<Names> = {} as PortExports_Input<Names>
+) {
+    return new _PortExports(portRecordInput(record)) as any as PortExports<Names>
+}
+
+@display({
+    simple(self) {
+        return `PortExports(${Object.keys(self._rec).join(", ")})`
+    }
+})
+class _PortExports {
+    constructor(readonly _rec: Record<string, Port_Full>) {}
+
+    private static _make(rec: Record<string, Port_Full>) {
+        return new _PortExports(rec)
+    }
+
+    private _apply(f: (rec: Record<string, Port_Full>) => Record<string, Port_Full>): _PortExports {
+        return _PortExports._make(f(this._rec))
+    }
+
+    union(other: _PortExports): _PortExports {
+        return this._apply(rec => Object.assign({}, rec, other._rec))
+    }
+
+    add(a: any, b?: any, c?: any): any {
+        if (!a) {
+            return this
+        }
+        if (c) {
+            return this._apply(rec =>
+                Object.assign({}, rec, {
+                    [a]: {
+                        name: a,
+                        port: +b,
+                        protocol: c.toUpperCase()
+                    }
+                })
+            )
+        }
+        if (b) {
+            return this._apply(rec => Object.assign({}, rec, { [a]: parsePortInput(a, b) }))
+        }
+        return this._apply(rec => {
+            const processed = portRecordInput(a)
+            return Object.assign({}, rec, processed)
+        })
+    }
+
+    pick(...name: string[]): _PortExports {
+        return this._apply(rec => pick(rec, name))
+    }
+
+    get names() {
+        return Object.keys(this._rec)
+    }
+
+    get(name: string): Port_Full {
+        if (!Object.hasOwn(this._rec, name)) {
+            throw new K8tsNetworkError(`Port ${name} not found`)
+        }
+        return this._rec[name]!
+    }
+
+    get values() {
+        return Object.values(this._rec)
+    }
+
+    get record() {
+        return this._rec
+    }
+
+    map(mapping: Record<string, number | boolean>): PortMap<any> {
+        return PortMap(
+            mapValues(this._rec, entry => {
+                if (!(entry.name in mapping)) {
+                    throw new K8tsNetworkError(`Port ${entry.name} not found in mapping`)
+                }
+                const portIn = mapping[entry.name]
+                let portVal: number
+                if (typeof portIn === "boolean") {
+                    portVal = entry.port
+                } else if (typeof portIn === "number") {
+                    portVal = portIn
+                } else {
+                    throw new K8tsNetworkError(
+                        `Port ${entry.name} mapping value must be a number or boolean`
+                    )
+                }
+                return {
+                    name: entry.name,
+                    protocol: entry.protocol,
+                    backend: entry.name,
+                    frontend: portVal as any
+                }
+            })
+        )
+    }
+}

package/src/expressions/network/ports/types.ts

@@ -1,11 +1,11 @@
-import type { Ip4, Ip4_String } from "../ip"
+import type { Ip4, Ip4_Input_String } from "../ip/ip4"
 
 type Port = number
-export type Port_Basic_Input = Port | `${Port}`
-export type Port_Protocol_Input = Port_Protocol | Lowercase<Port_Protocol>
+export type Port_Input_Scalar = Port | `${Port}`
+export type Port_Input_Protocol = Port_Protocol | Lowercase<Port_Protocol>
 export type Port_Protocol = "TCP" | "UDP"
-export type Port_WithProto_Input = `${Port}/${Port_Protocol_Input}`
-export interface Port_Mapping_Entry {
+export type Port_Input_WithProtocol = `${Port}/${Port_Input_Protocol}`
+export interface PortMap_Item {
     name: string
     protocol: Port_Protocol
     frontend: number
@@ -19,11 +19,25 @@ export interface Port_Full {
     hostPort?: number
 }
 
-export interface Port_Full_Input {
+export interface Port_Input_Object {
     port: Port
-    protocol?: Port_Protocol_Input
-    hostIp?: Ip4_String
+    protocol?: Port_Input_Protocol
+    hostIp?: Ip4_Input_String
     hostPort?: Port
 }
 
-export type Port_Input = Port_Full_Input | Port_Basic_Input | Port_WithProto_Input
+export type Port_Input = Port_Input_Object | Port_Input_Scalar | Port_Input_WithProtocol /**
+ * Input type for creating PortExports.
+ *
+ * A record mapping port names to their configurations, which can be:
+ *
+ * - A port number (uses TCP by default)
+ * - A tuple of `[port, protocol]`
+ * - A full port configuration object
+ *
+ * @template Names The union type of port names.
+ */
+
+export type PortExports_Input<Names extends string = string> = {
+    [K in Names]: Port_Input
+}

package/src/expressions/quantities/error.ts

@@ -0,0 +1,8 @@
+export class K8tsQuantityError extends Error {
+    name = "K8tsQuantityError" as const
+
+    constructor(message: string, fields: Record<string, any> & { cause?: Error } = {}) {
+        super(message)
+        Object.assign(this, fields)
+    }
+}

package/src/expressions/quantities/index.ts

@@ -1,2 +1,11 @@
-export * from "./reqlem"
-export * from "./units"
+export * from "./reqs/objects"
+export * from "./reqs/parser"
+export * from "./reqs/types"
+export * from "./reqs/values"
+
+export * from "./units/built-in"
+export * from "./units/dimension"
+export * from "./units/parser"
+export * from "./units/types"
+export * from "./units/value"
+export * from "./util"

package/src/expressions/quantities/reqs/objects.ts

@@ -0,0 +1,85 @@
+import { seq } from "doddle"
+import { mapValues } from "lodash"
+import { string, type Parjser } from "parjs"
+import { mapConst, or } from "parjs/combinators"
+import type { StringRecordLike } from "../../../utils/types"
+
+import { K8tsQuantityError } from "../error"
+import { UnitDimension } from "../units/dimension"
+import type { UnitValue } from "../units/value"
+import { createReqsParser } from "./parser"
+import type { Reqs_Dictionary, Reqs_ReqLimit } from "./types"
+import { Reqs_Values } from "./values"
+/** The Resource Requests object. */
+export class Reqs<const _Dimensions extends StringRecordLike<_Dimensions>> {
+    private readonly _unitParsers: Record<string, Parjser<UnitValue | undefined>>
+    private readonly _reqLimitParsers: Record<string, Parjser<Reqs_ReqLimit>>
+    private readonly _anyUnitParser = new UnitDimension({
+        name: "unknown",
+        units: "any"
+    })
+    private readonly _anyReqLimitParser = createReqsParser(this._anyUnitParser)
+    constructor(unitMap: {
+        [K in keyof _Dimensions]: UnitDimension<_Dimensions[K]>
+    }) {
+        const questionMarkParser = string("?").pipe(mapConst(undefined))
+        this._unitParsers = mapValues(unitMap, parser => parser.parser.pipe(or(questionMarkParser)))
+        this._reqLimitParsers = mapValues(unitMap, parser =>
+            createReqsParser(parser as UnitDimension)
+        )
+    }
+
+    private _parseReqLimit(resource: string, input: string): Reqs_ReqLimit {
+        const pReqLimit = this._reqLimitParsers[resource]
+        if (!pReqLimit) {
+            return this._anyReqLimitParser.parse(input).value
+        }
+        return pReqLimit.parse(input).value
+    }
+    __INPUT__!: Reqs_Dictionary<_Dimensions>
+
+    parse<const R extends Reqs_Dictionary<_Dimensions> | "=?">(input: R): Reqs_Values {
+        if (input === "=?") {
+        }
+        const allKeys = new Set([...Object.keys(input), ...Object.keys(this._unitParsers)])
+        const map = seq(allKeys)
+            .toRecord(key => {
+                const getVal = () => {
+                    const value = input[key as keyof R]
+                    const pUnitValue = this._unitParsers[key] ?? this._anyUnitParser.parser
+                    if (!pUnitValue) {
+                        throw new K8tsQuantityError(`No parser found for ${String(key)}`)
+                    }
+                    if (!value) {
+                        throw new K8tsQuantityError(`No value found for ${String(key)}`)
+                    }
+
+                    if (Array.isArray(value)) {
+                        // Singleton array is treated as `=X`, i.e. [exactly, exactly]
+                        // Pair is treated as `X->Y`, i.e. [request, limit]
+                        let [req, limit] = value.map(v => {
+                            return pUnitValue.parse(v as any).value
+                        })
+                        limit ??= req
+
+                        return {
+                            request: req,
+                            limit: limit
+                        }
+                    } else if (typeof value === "string") {
+                        return this._parseReqLimit(key as string, value)
+                    } else if (typeof value == "object" && "request" in value && "limit" in value) {
+                        return {
+                            request: pUnitValue.parse(value.request as any).value,
+                            limit: pUnitValue.parse(value.limit as any).value
+                        }
+                    } else {
+                        throw new K8tsQuantityError(`Invalid value for resource ${String(key)}`)
+                    }
+                }
+                return [key, getVal()] as const
+            })
+            .pull()
+        return new Reqs_Values(map)
+    }
+}

package/src/expressions/quantities/{reqlem → reqs}/parser.ts

@@ -1,9 +1,9 @@
 import { space, string } from "parjs"
 import { between, many, manySepBy, map, must, or, qthen } from "parjs/combinators"
-import type { UnitParser } from "../units/unit-parser"
-import type { ReqLimit } from "./types"
+import type { UnitDimension } from "../units/dimension"
+import type { Reqs_ReqLimit } from "./types"
 
-export function createResourceParser(pUnitValue: UnitParser) {
+export function createReqsParser(pUnitValue: UnitDimension) {
     const pSpaces = space().pipe(many())
     const rSeparator = string("->").pipe(between(pSpaces))
     const arrowExprParser = pUnitValue.parser.pipe(
@@ -21,7 +21,7 @@ export function createResourceParser(pUnitValue: UnitParser) {
             return {
                 request: a,
                 limit: b
-            } as ReqLimit
+            } as Reqs_ReqLimit
         })
     )
     const equalsExprParser = string("=").pipe(
@@ -30,7 +30,7 @@ export function createResourceParser(pUnitValue: UnitParser) {
             return {
                 request: x,
                 limit: x
-            } as ReqLimit
+            } as Reqs_ReqLimit
         })
     )
     return equalsExprParser.pipe(or(arrowExprParser))

package/src/expressions/quantities/reqs/types.ts

@@ -0,0 +1,35 @@
+import type { StringRecordLike } from "../../../utils/types"
+import type { Reqs_sUnitTerm } from "../units/types"
+import type { UnitValue } from "../units/value"
+
+export type Reqs_ReqLim_Array_FromTo<_Unit extends string> = [
+    Reqs_sUnitTerm<_Unit>,
+    Reqs_sUnitTerm<_Unit>
+]
+
+export type Reqs_ReqLim_Array_Exactly<_Unit extends string> = [Reqs_sUnitTerm<_Unit>]
+type _Spaces = "" | " " | "  "
+export type Reqs_sFromTo<_Unit extends string> =
+    `${Reqs_sUnitTerm<_Unit>}${_Spaces}->${_Spaces}${Reqs_sUnitTerm<_Unit>}`
+export type Reqs_sExactly<_Unit extends string> = `=${Reqs_sUnitTerm<_Unit>}`
+export interface Reqs_ReqLimit<_Unit extends string = string> {
+    readonly request?: UnitValue<_Unit>
+    readonly limit?: UnitValue<_Unit>
+}
+export interface Reqs_ReqLim_Object<_Unit extends string> {
+    request: Reqs_sUnitTerm<_Unit>
+    limit: Reqs_sUnitTerm<_Unit>
+}
+export type Reqs_One<_Unit extends string> =
+    | Reqs_sFromTo<_Unit>
+    | Reqs_sExactly<_Unit>
+    | Reqs_ReqLim_Array_FromTo<_Unit>
+    | Reqs_ReqLim_Array_Exactly<_Unit>
+    | Reqs_ReqLim_Object<_Unit>
+type CustomResource = `${string}/${string}`
+
+export type Reqs_Dictionary<UnitDict extends StringRecordLike<UnitDict>> = {
+    [K in keyof UnitDict]: Reqs_One<UnitDict[K]>
+} & {
+    [K in CustomResource]?: Reqs_One<string>
+}

package/src/expressions/quantities/reqs/values.ts

@@ -0,0 +1,47 @@
+import { isEmpty, mapValues, merge } from "lodash"
+import { toCdkQuantity, type CdkQuanitity } from "../util"
+import type { Reqs_ReqLimit } from "./types"
+
+export class Reqs_Values {
+    constructor(private _record: Record<string, Reqs_ReqLimit>) {}
+
+    get record() {
+        return this._record
+    }
+
+    private _toObjectTransform<T>(f: (value: string | number) => T): {
+        requests?: Record<string, T>
+        limits?: Record<string, T>
+    } {
+        const kubernetesForm = mapValues(this._record, (value, key) => {
+            const result = {} as any
+            if (value.request) {
+                result.requests = {
+                    [key]: f(value.request.val)
+                }
+            }
+            if (value.limit) {
+                result.limits = {
+                    [key]: f(value.limit.val)
+                }
+            }
+            if (!isEmpty(result)) {
+                return result
+            }
+            return undefined
+        })
+
+        return merge({}, ...Object.values(kubernetesForm).filter(x => x !== undefined))
+    }
+
+    toBareObject() {
+        return this._toObjectTransform(x => x)
+    }
+
+    toObject(): {
+        requests?: Record<string, CdkQuanitity>
+        limits?: Record<string, CdkQuanitity>
+    } {
+        return this._toObjectTransform(toCdkQuantity)
+    }
+}