@k8ts/instruments 0.1.0

package/src/image/family.ts

@@ -0,0 +1,71 @@
+export type JoinIfNotEmpty<A extends string, J extends string, B extends string> = A extends ""
+    ? B
+    : B extends ""
+      ? A
+      : `${A}${J}${B}`
+export class ImageHost<Text extends string = string> {
+    private readonly _url: Text
+    constructor(source: Text) {
+        this._url = source
+        this.toString = () => this[Symbol.toStringTag]
+    }
+
+    image<Image extends string>(name: Image) {
+        return new BaseImage<JoinIfNotEmpty<Text, "/", Image>>(this, name)
+    }
+
+    get [Symbol.toStringTag]() {
+        return this._url
+    }
+}
+
+export class BaseImage<Text extends string = string> {
+    constructor(
+        private readonly _source: ImageHost,
+        private readonly _name: string
+    ) {
+        this.toString = () => this[Symbol.toStringTag]
+    }
+
+    tag<Tag extends string>(tag: Tag) {
+        return new TaggedImage<JoinIfNotEmpty<Text, ":", Tag>>(this, tag)
+    }
+
+    get [Symbol.toStringTag]() {
+        if (this._source[Symbol.toStringTag] === "") {
+            return this._name
+        }
+        return [this._source, this._name].join("/")
+    }
+}
+
+export class TaggedImage<Text extends string = string> {
+    constructor(
+        private readonly _family: BaseImage<string>,
+        private readonly _tag: string
+    ) {
+        this.toString = () => this.text
+    }
+
+    get text() {
+        const fam = this._family[Symbol.toStringTag]
+        if (this._tag === "") {
+            return fam
+        }
+        return [fam, this._tag].join(":")
+    }
+
+    get [Symbol.toStringTag]() {
+        return this.text
+    }
+}
+
+export namespace Image {
+    export function name<Name extends string>(name: Name) {
+        return new ImageHost("").image(name)
+    }
+
+    export function host<Host extends string>(url: Host) {
+        return new ImageHost(url)
+    }
+}

package/src/image/index.ts

@@ -0,0 +1 @@
+export { BaseImage, Image, ImageHost, TaggedImage } from "./family"

package/src/index.ts

@@ -0,0 +1,18 @@
+export * from "./_embedder"
+export * from "./_string"
+export * from "./api-kind"
+export * from "./cmd"
+export * from "./displayers"
+export * from "./env"
+export * from "./forward-exports"
+export * from "./graph"
+export * from "./image"
+export * from "./kind-map"
+export * from "./manifest"
+export * from "./ports"
+export * from "./producer"
+export * from "./ref-key"
+export * from "./reference"
+export * from "./resources"
+export * from "./tracing"
+export * from "./units"

package/src/kind-map/index.ts

@@ -0,0 +1,150 @@
+import { Map, type Set } from "immutable"
+import { Kind } from "../api-kind"
+import { InstrumentsError } from "../error"
+import { RefKey } from "../ref-key"
+const separator = "/"
+export type LookupKey = NodeEntry[keyof NodeEntry]
+interface NodeEntry {
+    kind: string
+    class: Function
+    ident: Kind.Identifier
+}
+export class KindMap {
+    constructor(
+        private _entryMap: Map<LookupKey, NodeEntry> = Map([]) as any,
+        private _parent: KindMap | undefined = undefined
+    ) {}
+
+    refKey<Kind extends string, Name extends string>(
+        kind: Kind | Kind.Identifier<Kind>,
+        name: Name
+    ): RefKey<Kind, Name> {
+        const trueKind = this.getKind(kind)
+        return new RefKey.RefKey(trueKind, name) as any
+    }
+
+    private _bindEntry(entry: NodeEntry) {
+        for (const key of [entry.kind, entry.class, entry.ident]) {
+            this._entryMap = this._entryMap.set(key, entry)
+        }
+    }
+
+    add(kind: Kind.Identifier, klass: Function) {
+        this._bindEntry({
+            kind: kind.name,
+            class: klass,
+            ident: kind
+        })
+    }
+
+    parse(ref: string | RefKey) {
+        const result = this.tryParse(ref)
+        if (!result) {
+            throw new InstrumentsError(`Could not parse reference key: ${ref}`)
+        }
+        return result
+    }
+
+    tryParse(ref: unknown): RefKey.RefKey | undefined {
+        if (typeof ref !== "string" && typeof ref !== "object") {
+            return undefined
+        }
+        if (ref == null) {
+            return undefined
+        }
+        if (ref instanceof RefKey.RefKey) {
+            return ref
+        }
+        if (typeof ref === "object") {
+            return undefined
+        }
+        const [kind, name] = ref.split(separator).map(s => s.trim())
+        if (!kind || !name) {
+            return undefined
+        }
+        return this.refKey(kind, name)
+    }
+
+    get kinds(): Set<string> {
+        return this._entryMap
+            .keySeq()
+            .filter(k => typeof k === "string")
+            .toSet()
+    }
+
+    private _unknownNameError(kind: string) {
+        return new InstrumentsError(`The shorthand name ${kind} is not registered`)
+    }
+    private _unknownIdentError(ident: Kind.Identifier) {
+        return new InstrumentsError(`The kind identifier ${ident} is not registered`)
+    }
+    private _unknownClassError(klass: Function) {
+        return new InstrumentsError(`The class ${klass.name} is not registered`)
+    }
+    private _convert(something: LookupKey | RefKey.RefKey) {
+        if (typeof something === "string") {
+            if (something.includes("/")) {
+                return this.parse(something).kind
+            }
+            return something
+        } else if (typeof something === "function" || something instanceof Kind.Identifier) {
+            return something
+        } else if (something instanceof RefKey.RefKey) {
+            return something.kind
+        }
+        throw new InstrumentsError(`Invalid argument ${something}`)
+    }
+    private _getEntry(key: LookupKey | RefKey.RefKey) {
+        const converted = this._convert(key)
+        const entry = this._tryGetEntry(key)
+        if (!entry) {
+            if (typeof converted === "string") {
+                throw this._unknownNameError(converted)
+            } else if (converted instanceof Kind.Identifier) {
+                throw this._unknownIdentError(converted)
+            } else if (typeof converted === "function") {
+                throw this._unknownClassError(converted)
+            }
+        }
+        return entry!
+    }
+    private _tryGetEntry(key: LookupKey | RefKey.RefKey): NodeEntry | undefined {
+        const converted = this._convert(key)
+        return this._entryMap.get(converted) ?? this._parent?._tryGetEntry(converted) ?? undefined
+    }
+
+    tryGetKind<Name extends string>(refKey: RefKey.RefKey<Name>): Kind.Identifier<Name> | undefined
+    tryGetKind<F extends Kind.Identifier>(klass: F): F
+    tryGetKind<Name extends string>(kind: Name): Kind.Identifier<Name> | undefined
+    tryGetKind(key: LookupKey): Kind.Identifier | undefined
+    tryGetKind(kindOrIdent: LookupKey | RefKey.RefKey): Kind.Identifier | undefined {
+        return this._tryGetEntry(kindOrIdent)?.ident
+    }
+
+    getKind<K extends Kind.Identifier>(kind: K): K
+    getKind<Name extends string>(kind: Name): Kind.Identifier<Name>
+    getKind(kindOrClass: LookupKey): Kind.Identifier
+    getKind(kindOrClass: string | Function): Kind.Identifier {
+        return this._getEntry(kindOrClass).ident
+    }
+
+    tryGetClass(refKey: RefKey.RefKey): Function | undefined
+    tryGetClass<F extends Function>(klass: F): F
+    tryGetClass(kind: string): Function | undefined
+    tryGetClass(ident: Kind.Identifier): Function | undefined
+    tryGetClass(kindOrIdent: LookupKey | RefKey.RefKey): Function | undefined {
+        return this._tryGetEntry(kindOrIdent)?.class
+    }
+
+    getClass(refKey: RefKey.RefKey): Function
+    getClass<F extends Function>(klass: F): F
+    getClass(kind: string): Function
+    getClass<T extends Function | string>(kindOrClass: T): T extends Function ? string : Function
+    getClass(kindOrClass: string | Function | RefKey.RefKey): Function | string {
+        return this._getEntry(kindOrClass).class
+    }
+
+    has(kindOrClass: LookupKey): boolean {
+        return this._entryMap.has(kindOrClass as any)
+    }
+}

package/src/manifest/index.ts

@@ -0,0 +1,53 @@
+import { Embedder } from "../_embedder/base"
+import { ResourceEntity } from "../graph/resource-node"
+export interface ManifestMetadata {
+    labels: Record<string, string>
+    annotations: Record<string, string>
+    name: string
+    namespace?: string
+}
+export interface ManifestIdentFields {
+    kind: string
+    apiVersion: string
+}
+export interface BuilderInputTypes {
+    body: PreManifest
+    metadata?: ManifestMetadata
+    idents?: ManifestIdentFields
+}
+
+export type JsonSerializable =
+    | string
+    | number
+    | boolean
+    | null
+    | JsonSerializable[]
+    | { [key: string]: JsonSerializable }
+
+export interface PreManifest {
+    metadata?: {
+        name?: string
+        namespace?: string
+        annotations?: Record<string, string>
+        labels?: Record<string, string>
+    }
+}
+export interface BaseManifest {
+    [key: string]: JsonSerializable
+    [key: number]: never
+    apiVersion: string
+    kind: string
+    metadata: {
+        name: string
+        namespace?: string
+        labels?: Record<string, string>
+        annotations?: Record<string, string>
+    }
+}
+
+export interface SpecManifest<T extends JsonSerializable> extends BaseManifest {
+    spec: T
+}
+
+export const ManifestSourceEmbedder = new Embedder<object, ResourceEntity>("ManifestSource")
+export * from "./manifest-builder"

package/src/manifest/manifest-builder.ts

@@ -0,0 +1,98 @@
+import {
+    BaseManifest,
+    ManifestIdentFields,
+    ManifestMetadata,
+    ManifestSourceEmbedder,
+    PreManifest
+} from "."
+import { Embedder } from "../_embedder/base"
+import { MetadataEntity } from "../graph/resource-node"
+
+export namespace ManifestBuilder {
+    export interface Out {
+        body: () => PreManifest
+        metadata: () => ManifestMetadata
+        ident: () => ManifestIdentFields
+        manifest: () => BaseManifest
+    }
+
+    export type In<Target extends MetadataEntity = MetadataEntity> = Partial<{
+        [K in keyof Out]: (self: Target) => ReturnType<Out[K]>
+    }> & {
+        body: (self: Target) => PreManifest
+    } & {
+        [key: string]: (self: Target, ...args: any[]) => any
+    }
+}
+
+class BuilderDecorator {
+    private _system = new Embedder<MetadataEntity, ManifestBuilder.In>("builder")
+
+    implement(
+        ctor: { new (...args: any[]): MetadataEntity },
+        input: ManifestBuilder.In<MetadataEntity>
+    ) {
+        this._system.set(ctor.prototype, {
+            ...input
+        })
+    }
+    private _metadata(self: MetadataEntity) {
+        return {
+            name: self.meta.get("name"),
+            namespace: self.meta.tryGet("namespace"),
+            labels: self.meta.labels,
+            annotations: self.meta.annotations
+        }
+    }
+
+    private _idents(self: MetadataEntity) {
+        return {
+            apiVersion: self.kind.parent!.text,
+            kind: self.kind.name
+        }
+    }
+
+    manifest(trait: ManifestBuilder.Out, self: MetadataEntity) {
+        const mani = {
+            ...trait.ident(),
+            metadata: trait.metadata(),
+            ...trait.body()
+        }
+        ManifestSourceEmbedder.set(mani, self)
+        return mani
+    }
+
+    idents(self: MetadataEntity) {
+        return {
+            kind: self.kind.name,
+            apiVersion: self.kind.parent!.text
+        }
+    }
+    get(target: MetadataEntity): ManifestBuilder.Out {
+        const input = this._system.get(target)
+        const o: ManifestBuilder.Out = {
+            ident: () => input.ident?.call(o, target) ?? this._idents(target),
+            metadata: () => input.metadata?.call(o, target) ?? this._metadata(target),
+            body: () => input.body.call(o, target),
+            manifest: () => this.manifest(o, target) as any
+        }
+        return o
+    }
+
+    get decorator() {
+        return <Target extends new (...args: any[]) => MetadataEntity>(
+            input: ManifestBuilder.In<InstanceType<Target>>
+        ) => {
+            return (ctor: Target) => {
+                this.implement(ctor, input as any)
+                return ctor
+            }
+        }
+    }
+}
+
+export const Builder = new BuilderDecorator()
+
+export const manifest = Builder.decorator
+
+// writing the decorator itself

package/src/ports/error.ts

@@ -0,0 +1,8 @@
+export class PortError extends Error {
+    override name = "PortError"
+    constructor(message: string, extra: Record<string, any> = {}) {
+        super(message)
+        this.name = "PortError"
+        Object.assign(this, extra)
+    }
+}

package/src/ports/index.ts

@@ -0,0 +1,8 @@
+import { PortSet } from "./set"
+import type { InputPortSetRecord } from "./types"
+export { PortMap } from "./map"
+export { PortSet } from "./set"
+export { InputPortMapping, InputPortSetRecord, PortMapEntry, PortSetEntry } from "./types"
+export function ports<Names extends string>(input: InputPortSetRecord<Names>): PortSet<Names> {
+    return PortSet.make(input)
+}

package/src/ports/map.ts

@@ -0,0 +1,41 @@
+import { Map } from "immutable"
+import { PortError } from "./error"
+import type { PortMapEntry } from "./types"
+export class PortMap<Names extends string> {
+    constructor(private readonly _map: Map<string, PortMapEntry>) {}
+
+    private _apply(f: (map: Map<string, PortMapEntry>) => Map<string, PortMapEntry>): PortMap<any> {
+        return new PortMap(f(this._map))
+    }
+
+    pick<InNames extends Names>(...name: InNames[]): PortMap<InNames> {
+        return this._apply(map => map.filter((_, key) => name.includes(key as InNames)))
+    }
+
+    get values() {
+        return this._map
+    }
+
+    map(mapping: Record<Names, number>): PortMap<Names> {
+        return new PortMap(
+            this._map.map(entry => {
+                return {
+                    ...entry,
+                    source: entry.target,
+                    target: mapping[entry.name as keyof typeof mapping]
+                }
+            })
+        )
+    }
+
+    get(name: Names): PortMapEntry {
+        if (!this._map.has(name)) {
+            throw new PortError(`Port ${name} not found`)
+        }
+        return this._map.get(name) as PortMapEntry
+    }
+
+    toMap() {
+        return this._map
+    }
+}

package/src/ports/set.ts

@@ -0,0 +1,79 @@
+import { Map } from "immutable"
+import { PortError } from "./error"
+import { PortMap } from "./map"
+import { parsePortInput, portRecordInput } from "./tools/entry"
+import type {
+    InputPort,
+    InputPortMapping,
+    InputPortSetEntry,
+    InputPortSetRecord,
+    InputProtocol,
+    PortSetEntry
+} from "./types"
+
+declare const __NAMES__: unique symbol
+export class PortSet<Names extends string = never> {
+    constructor(private readonly _map: Map<Names, PortSetEntry> = Map()) {}
+
+    private _apply(f: (map: Map<string, PortSetEntry>) => Map<string, PortSetEntry>) {
+        return new PortSet(f(this._map))
+    }
+
+    union<InNames extends string>(other: PortSet<InNames>): PortSet<Names | InNames> {
+        return new PortSet(this._map.merge(other._map))
+    }
+    add<Name extends string>(
+        name: Name,
+        port: InputPort,
+        protocol: InputProtocol
+    ): PortSet<Names | Name>
+    add<Name extends string>(name: Name, entry: InputPortSetEntry): PortSet<Names | Name>
+    add<InNames extends string>(input: InputPortSetRecord<InNames>): PortSet<Names | InNames>
+    add(a: any, b?: any, c?: any): any {
+        if (c) {
+            return this._apply(map => map.set(a, { name: a, port: +b, protocol: c.toUpperCase() }))
+        }
+        if (b) {
+            return this._apply(map => map.set(a, parsePortInput(a, b)))
+        }
+        return this._apply(map => {
+            const processed = portRecordInput(a)
+            return map.merge(processed)
+        })
+    }
+
+    pick<InNames extends Names>(...name: InNames[]): PortSet<InNames> {
+        return this._apply(map => map.filter((_, key) => name.includes(key as InNames))) as any
+    }
+
+    get(name: Names): PortSetEntry {
+        if (!this._map.has(name)) {
+            throw new PortError(`Port ${name} not found`)
+        }
+        return this._map.get(name)!
+    }
+
+    get values() {
+        return this._map
+    }
+
+    map(mapping: InputPortMapping<Names>): PortMap<Names> {
+        return new PortMap(
+            this._map.map(entry => {
+                if (!(entry.name in mapping)) {
+                    throw new PortError(`Port ${entry.name} not found in mapping`)
+                }
+                return {
+                    name: entry.name,
+                    protocol: entry.protocol,
+                    source: entry.port,
+                    target: mapping[entry.name as keyof typeof mapping]
+                }
+            })
+        )
+    }
+
+    static make<Names extends string>(input: InputPortSetRecord<Names>) {
+        return new PortSet().add(input)
+    }
+}

package/src/ports/tools/entry.ts

@@ -0,0 +1,43 @@
+import { Map } from "immutable"
+import { PortSet } from "../set"
+import type {
+    InputPortSetEntry,
+    InputPortSetRecord,
+    InputPortSetSpec,
+    PortSetEntry,
+    Protocol
+} from "../types"
+import { parsePortSpec } from "./parse"
+
+function portSetEntry(name: string, value: InputPortSetEntry): PortSetEntry {
+    return {
+        name,
+        port: value.port,
+        protocol: value.protocol.toUpperCase() as Protocol
+    }
+}
+
+export function parsePortInput(name: string, input: InputPortSetSpec): PortSetEntry {
+    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: InputPortSetRecord<string> | PortSet<string>
+): Map<string, PortSetEntry> {
+    if (record instanceof PortSet) {
+        return record.values
+    }
+    const inputMap = Map(record)
+    return inputMap
+        .map((v, k) => parsePortInput(k, v))
+        .map((value, key) => portSetEntry(key, value))
+}

package/src/ports/tools/parse.ts

@@ -0,0 +1,40 @@
+import { anyStringOf, int, string } from "parjs"
+import { map, maybe, must, qthen, then } from "parjs/combinators"
+import { PortError } from "../error"
+import type { InputPortSetEntry, Protocol } from "../types"
+
+function validatePort(port: number) {
+    if (port < 0 || port > 65535) {
+        return {
+            kind: "Hard" as const,
+            message: "Port must be between 0 and 65535"
+        }
+    }
+    return true
+}
+const pProtocol = anyStringOf("tcp", "udp", "TCP", "UDP").pipe(
+    map(s => s.toUpperCase() as Protocol)
+)
+
+const pPort = int().pipe(must(validatePort))
+const pProtocolPart = string("/").pipe(qthen(pProtocol), maybe("TCP"))
+const pPortSpec = pPort.pipe(
+    then(pProtocolPart),
+    map(arr => {
+        const [port, protocol] = arr
+        return {
+            port,
+            protocol: protocol?.toUpperCase() ?? "TCP"
+        } as InputPortSetEntry
+    })
+)
+
+export function parsePortSpec(name: string, input: string) {
+    const result = pPortSpec.parse(input)
+    if (result.kind === "OK") {
+        return result.value
+    }
+    throw new PortError(name, {
+        parseError: result.reason
+    })
+}

package/src/ports/types.ts

@@ -0,0 +1,42 @@
+export interface PortSpecObj {
+    port: Port
+    protocol: Protocol
+}
+
+export type Port = number
+export type InputPort = Port | `${Port}`
+export type InputProtocol = Protocol | Lowercase<Protocol>
+export type Protocol = "TCP" | "UDP"
+export type InputPortProto = `${Port}/${InputProtocol}`
+export interface PortMapEntry {
+    name: string
+    protocol: Protocol
+    source: number
+    target: number
+}
+
+export interface PortSetEntry {
+    name: string
+    port: number
+    protocol: Protocol
+}
+
+export interface InputPortSetEntry {
+    port: Port
+    protocol: InputProtocol
+}
+
+export type InputPortSetSpec = InputPortSetEntry | InputPort | InputPortProto
+
+export interface InputPortMapEntry {
+    source: Port
+    target: Port
+    protocol: InputProtocol
+}
+
+export type InputPortSetRecord<Names extends string = string> = {
+    [K in Names]: InputPortSetSpec
+}
+export type InputPortMapping<Names extends string = string> = {
+    [K in Names]: number
+}

package/src/producer/index.ts

@@ -0,0 +1 @@
+export * from "./producer"

package/src/producer/producer.ts

@@ -0,0 +1,18 @@
+export type Producer<Factory extends object, Thing extends object> = Producer.Producer<
+    Factory,
+    Thing
+>
+export namespace Producer {
+    export type Producer<Factory extends object, Produced extends object> = (
+        factory: Factory
+    ) => Iterable<Produced>
+
+    export function map<Factory extends object, Produced extends object, NewInput extends object>(
+        producer: Producer<Factory, Produced>,
+        projection: (input: NewInput) => Factory
+    ) {
+        return function bound_producer(input: NewInput) {
+            return producer(projection(input))
+        }
+    }
+}

package/src/ref-key/index.ts

@@ -0,0 +1 @@
+export * from "./ref-key"