@highstate/library 0.14.2 → 0.16.0

package/src/network/address-space.ts

@@ -0,0 +1,94 @@
+import { defineEntity, defineUnit, z } from "@highstate/contract"
+import { l3EndpointEntity } from "./endpoint"
+import { subnetEntity } from "./subnet"
+
+export type AddressSpace = z.infer<typeof addressSpaceEntity.schema>
+
+/**
+ * The entity representing a network address space.
+ */
+export const addressSpaceEntity = defineEntity({
+  type: "network.address-space.v1",
+
+  includes: {
+    /**
+     * The minimal set of subnets that fully cover the address space.
+     */
+    subnets: {
+      entity: subnetEntity,
+      multiple: true,
+    },
+  },
+
+  schema: z.unknown(),
+
+  meta: {
+    color: "#3F51B5",
+  },
+})
+
+/**
+ * Defines an address space from a list of addresses/subnets/ranges.
+ */
+export const addressSpace = defineUnit({
+  type: "network.address-space.v1",
+
+  args: {
+    /**
+     * The list of addresses to include in the address space.
+     *
+     * The supported formats 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: z.string().array().default([]),
+
+    /**
+     * The list of addresses to exclude from the `addresses` list.
+     *
+     * The supported formats are the same as in `addresses`.
+     */
+    excluded: z.string().array().default([]),
+  },
+
+  inputs: {
+    /**
+     * The endpoints to include in the address space.
+     */
+    included: {
+      entity: l3EndpointEntity,
+      multiple: true,
+      required: false,
+    },
+
+    /**
+     * The endpoints to exclude from the `included` list.
+     */
+    excluded: {
+      entity: l3EndpointEntity,
+      multiple: true,
+      required: false,
+    },
+  },
+
+  outputs: {
+    /**
+     * The address space entity representing the created address space.
+     */
+    addressSpace: addressSpaceEntity,
+  },
+
+  meta: {
+    title: "Address Space",
+    icon: "mdi:network",
+    category: "Network",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/network/address-space",
+  },
+})

package/src/network/address.ts

@@ -0,0 +1,33 @@
+import { defineEntity, z } from "@highstate/contract"
+import { addressTypeSchema, subnetEntity } from "./subnet"
+
+export type Address = z.infer<typeof addressEntity.schema>
+
+export const addressEntity = defineEntity({
+  type: "network.address.v1",
+
+  includes: {
+    /**
+     * The subnet to which the address belongs.
+     */
+    subnet: subnetEntity,
+  },
+
+  schema: z.object({
+    /**
+     * The type of the address.
+     */
+    type: addressTypeSchema,
+
+    /**
+     * The address in canonical string representation.
+     *
+     * IPv6 addresses must be in shortest possible notation as per RFC 5952.
+     *
+     * For example:
+     * - IPv4: `192.168.1.1`
+     * - IPv6: `2001:db8:85a3::8a2e:370:7334`
+     */
+    value: z.string(),
+  }),
+})

package/src/network/dynamic-endpoint.ts

@@ -0,0 +1,39 @@
+import { defineEntity, z } from "@highstate/contract"
+import { implementationReferenceSchema } from "../impl-ref"
+import { l3EndpointSchema } from "./endpoint-schema"
+
+export type DynamicL3Endpoint = z.infer<typeof dynamicL3EndpointEntity.schema>
+export type DynamicL4Endpoint = z.infer<typeof dynamicL4EndpointEntity.schema>
+export type DynamicL7Endpoint = z.infer<typeof dynamicL7EndpointEntity.schema>
+
+function defineDynamicEndpointEntity<TLevel extends number, TSchema extends z.ZodType>(
+  level: TLevel,
+  endpointSchema: TSchema,
+) {
+  return defineEntity({
+    type: `network.dynamic-l${level}-endpoint.v1`,
+
+    schema: z.union([
+      z.object({
+        type: z.literal("static"),
+
+        /**
+         * The static endpoint.
+         */
+        endpoint: endpointSchema,
+      }),
+      z.object({
+        type: z.literal("dynamic"),
+
+        /**
+         * The implementation reference to resolve the dynamic endpoint.
+         */
+        implRef: implementationReferenceSchema,
+      }),
+    ]),
+  })
+}
+
+export const dynamicL3EndpointEntity = defineDynamicEndpointEntity(3, l3EndpointSchema)
+export const dynamicL4EndpointEntity = defineDynamicEndpointEntity(4, l3EndpointSchema)
+export const dynamicL7EndpointEntity = defineDynamicEndpointEntity(7, l3EndpointSchema)

package/src/network/endpoint-schema.ts

@@ -0,0 +1,116 @@
+import { z } from "@highstate/contract"
+import { metadataSchema } from "../utils"
+import { addressEntity } from "./address"
+
+function createEndpointSchema<TLevel extends number, TShape extends z.core.$ZodShape>(
+  level: TLevel,
+  shape: TShape,
+) {
+  return z.intersection(
+    z.object({
+      /**
+       * The level of the endpoint in the network stack.
+       */
+      level: z.literal(level).default(level),
+
+      /**
+       * The extra metadata for the endpoint.
+       *
+       * In most cases, this is provided by the endpoint origin (e.g., a Kubernetes service).
+       */
+      metadata: z.intersection(
+        metadataSchema,
+        z.object({
+          /**
+           * The scope of the endpoint as per IANA definitions.
+           *
+           * - `private`: The endpoint is intended for use within a private network.
+           * - `global`: The endpoint is intended for public access over the internet.
+           *
+           * If not specified, the scope is considered unknown.
+           */
+          "iana.scope": z.enum(["private", "global"]).optional(),
+        }),
+      ),
+
+      ...shape,
+    }),
+    z.union([
+      z.object({
+        type: z.literal("hostname"),
+
+        /**
+         * The hostname of the endpoint in the format of a domain name as per RFC 1035.
+         */
+        hostname: z.string(),
+
+        address: z.undefined().optional(),
+      }),
+      z.object({
+        type: z.enum(["ipv4", "ipv6"]),
+
+        /**
+         * The address entity representing the IP address of the endpoint.
+         */
+        address: addressEntity.schema,
+
+        hostname: z.undefined().optional(),
+      }),
+    ]),
+  )
+}
+
+export const l4ProtocolSchema = z.enum(["tcp", "udp"])
+
+/**
+ * The schema for a TCP/UDP port.
+ */
+export const portSchema = z.number().int().min(1).max(65535)
+
+export const l4PortInfoSchema = z.object({
+  port: portSchema,
+  protocol: l4ProtocolSchema,
+})
+
+export const l7AppInfoSchema = z.object({
+  /**
+   * The name of the application protocol used by the endpoint.
+   */
+  appProtocol: z.string(),
+
+  /**
+   * The resource path of the application endpoint, including query parameters.
+   * Must not start with a slash (`/`).
+   *
+   * Example: `api/v1/resource?query=value`, `database?param=value`, `user/repo.git`.
+   */
+  path: z.string().optional(),
+})
+
+const onlyl3EndpointSchema = createEndpointSchema(3, {
+  port: z.undefined().optional(),
+  protocol: z.undefined().optional(),
+  appProtocol: z.undefined().optional(),
+  path: z.undefined().optional(),
+})
+
+const onlyl4EndpointSchema = createEndpointSchema(4, {
+  ...l4PortInfoSchema.shape,
+  appProtocol: z.undefined().optional(),
+  path: z.undefined().optional(),
+})
+
+const onlyl7EndpointSchema = createEndpointSchema(7, {
+  ...l4PortInfoSchema.shape,
+  ...l7AppInfoSchema.shape,
+})
+
+export const l3EndpointSchema = z.union([
+  onlyl3EndpointSchema,
+  onlyl4EndpointSchema,
+  onlyl7EndpointSchema,
+])
+
+export const l4EndpointSchema = z.union([onlyl4EndpointSchema, onlyl7EndpointSchema])
+
+export const l7EndpointSchema = onlyl7EndpointSchema

package/src/network/endpoint.ts

@@ -0,0 +1,347 @@
+import type { Simplify } from "type-fest"
+import { $args, defineEntity, defineUnit, z } from "@highstate/contract"
+import { mapValues, pick } from "remeda"
+import { metadataSchema } from "../utils"
+import { addressEntity } from "./address"
+import {
+  dynamicL3EndpointEntity,
+  dynamicL4EndpointEntity,
+  dynamicL7EndpointEntity,
+} from "./dynamic-endpoint"
+import {
+  l3EndpointSchema,
+  l4EndpointSchema,
+  type l4PortInfoSchema,
+  type l4ProtocolSchema,
+  type l7AppInfoSchema,
+  l7EndpointSchema,
+} from "./endpoint-schema"
+import { subnetEntity } from "./subnet"
+
+/**
+ * The L3 endpoint for some service.
+ *
+ * May be a domain name or an IP address.
+ */
+export const l3EndpointEntity = defineEntity({
+  type: "network.l3-endpoint.v1",
+
+  includes: {
+    /**
+     * The subnet containing the endpoint.
+     *
+     * If type is "hostname", will be omitted.
+     */
+    subnet: {
+      entity: subnetEntity,
+      required: false,
+    },
+
+    /**
+     * The address of the endpoint.
+     *
+     * If type is "hostname", will be omitted.
+     */
+    address: {
+      entity: addressEntity,
+      required: false,
+    },
+
+    /**
+     * The dynamic endpoint which statically resolves to this endpoint.
+     *
+     * Allows to use any static endpoint as a dynamic without extra units.
+     */
+    dynamic: {
+      entity: dynamicL3EndpointEntity,
+      required: false,
+    },
+  },
+
+  schema: l3EndpointSchema,
+
+  meta: {
+    color: "#4CAF50",
+  },
+})
+
+/**
+ * The schema for an IPv4 prefix length.
+ */
+export const ipv4PrefixSchema = z.number().int().min(0).max(32)
+
+/**
+ * The schema for address that can be either IPv4 or IPv6.
+ */
+export const ipv46Schema = z.union([z.ipv4(), z.ipv6()])
+
+/**
+ * The L4 endpoint for some service.
+ *
+ * Extends an L3 endpoint with a port and protocol.
+ */
+export const l4EndpointEntity = defineEntity({
+  type: "network.l4-endpoint.v1",
+
+  extends: { l3EndpointEntity },
+
+  includes: {
+    /**
+     * The dynamic endpoint which statically resolves to this endpoint.
+     *
+     * Allows to use any static endpoint as a dynamic without extra units.
+     */
+    dynamic: dynamicL4EndpointEntity,
+  },
+
+  schema: l4EndpointSchema,
+
+  meta: {
+    color: "#2196F3",
+  },
+})
+
+/**
+ * The L7 endpoint for some service.
+ *
+ * Extends an L4 endpoint with application protocol information.
+ */
+export const l7EndpointEntity = defineEntity({
+  type: "network.l7-endpoint.v1",
+
+  extends: { l4EndpointEntity },
+
+  includes: {
+    /**
+     * The dynamic endpoint which statically resolves to this endpoint.
+     *
+     * Allows to use any static endpoint as a dynamic without extra units.
+     */
+    dynamic: dynamicL7EndpointEntity,
+  },
+
+  schema: l7EndpointSchema,
+
+  meta: {
+    color: "#FF9800",
+  },
+})
+
+export const endpointArgs = $args({
+  /**
+   * The custom metadata entries of the endpoint.
+   *
+   * Can be used to filter them (for example, by environment, region, etc.).
+   */
+  metadata: metadataSchema,
+})
+
+/**
+ * The component which creates an L3 endpoint.
+ */
+export const l3Endpoint = defineUnit({
+  type: "network.l3-endpoint.v1",
+
+  args: {
+    /**
+     * The string representation of the endpoint.
+     *
+     * May be a domain name or an IP address.
+     */
+    endpoint: z.string(),
+
+    ...endpointArgs,
+  },
+
+  outputs: {
+    endpoint: l3EndpointEntity,
+  },
+
+  meta: {
+    title: "L3 Endpoint",
+    icon: "mdi:network-outline",
+    iconColor: "#4CAF50",
+    defaultNamePrefix: "endpoint",
+    category: "Network",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/network/l3-endpoint",
+  },
+})
+
+/**
+ * The component which creates an L4 endpoint.
+ */
+export const l4Endpoint = defineUnit({
+  type: "network.l4-endpoint.v1",
+
+  args: {
+    /**
+     * The string representation of the endpoint.
+     *
+     * May be a domain name or an IP address + port/protocol.
+     *
+     * The possible formats are:
+     *
+     * - `endpoint:port` (TCP by default)
+     * - `tcp://endpoint:port`
+     * - `udp://endpoint:port`
+     */
+    endpoint: z.string(),
+
+    ...endpointArgs,
+  },
+
+  outputs: {
+    endpoint: l4EndpointEntity,
+  },
+
+  meta: {
+    title: "L4 Endpoint",
+    icon: "mdi:network-outline",
+    iconColor: "#2196F3",
+    defaultNamePrefix: "endpoint",
+    category: "Network",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/network/l4-endpoint",
+  },
+})
+
+/**
+ * The component which creates an L7 endpoint.
+ */
+export const l7Endpoint = defineUnit({
+  type: "network.l7-endpoint.v1",
+
+  args: {
+    /**
+     * The string representation of the endpoint.
+     *
+     * The format is `[protocol://]endpoint[:port][/path]`.
+     */
+    endpoint: z.string(),
+
+    /**
+     * The L4 protocol of the endpoint.
+     *
+     * If not specified, it will be inferred from the endpoint string if possible or default to `tcp`.
+     */
+    protocol: z.enum(["infer", "tcp", "udp"]).default("infer"),
+
+    ...endpointArgs,
+  },
+
+  outputs: {
+    endpoint: l7EndpointEntity,
+  },
+
+  meta: {
+    title: "L7 Endpoint",
+    icon: "mdi:network-outline",
+    iconColor: "#FF9800",
+    defaultNamePrefix: "endpoint",
+    category: "Network",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/network/l7-endpoint",
+  },
+})
+
+export const networkArgs = $args({
+  /**
+   * The filter expression to select endpoints by their properties and metadata.
+   *
+   * The following properties are available for filtering:
+   *
+   * - `type`: The type of the endpoint (`ipv4`, `ipv6`, `hostname`).
+   * - `level`: The level of the endpoint in the network stack (`3`, `4`, `7`). Numeric, can be used in expressions like `level >= 4`.
+   * - `protocol`: The L4 protocol of the endpoint (`tcp`, `udp`). Only available for L4 and L7 endpoints.
+   * - `port`: The port of the endpoint. Only available for L4 and L7 endpoints.
+   * - `appProtocol`: The application protocol of the endpoint (e.g., `http`, `https`, `dns`). Only available for L7 endpoints.
+   * - `metadata.{key}`: Any custom metadata field added to the endpoint. Nested fields (e.g., `metadata.k8s.service.clusterId`) are supported.
+   *
+   * See [filter-expression](https://github.com/tronghieu/filter-expression?tab=readme-ov-file#language) for more details on the expression syntax.
+   */
+  endpointFilter: z.string().meta({ language: "javascript" }),
+})
+
+export const optionalNetworkArgs = mapValues(networkArgs, x => ({ schema: x.schema.optional() }))
+
+/**
+ * Explicitly filter endpoints by their accessibility.
+ */
+export const endpointFilter = defineUnit({
+  type: "network.endpoint-filter.v1",
+
+  args: {
+    ...pick(networkArgs, ["endpointFilter"]),
+  },
+
+  inputs: {
+    l3Endpoints: {
+      entity: l3EndpointEntity,
+      multiple: true,
+      required: false,
+    },
+    l4Endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+      required: false,
+    },
+    l7Endpoints: {
+      entity: l7EndpointEntity,
+      multiple: true,
+      required: false,
+    },
+  },
+
+  outputs: {
+    l3Endpoints: {
+      entity: l3EndpointEntity,
+      multiple: true,
+    },
+    l4Endpoints: {
+      entity: l4EndpointEntity,
+      multiple: true,
+    },
+    l7Endpoints: {
+      entity: l7EndpointEntity,
+      multiple: true,
+    },
+  },
+
+  meta: {
+    title: "Endpoint Filter",
+    icon: "mdi:network-outline",
+    iconColor: "#FF9800",
+    secondaryIcon: "mdi:filter-outline",
+    category: "Network",
+  },
+
+  source: {
+    package: "@highstate/common",
+    path: "units/network/endpoint-filter",
+  },
+})
+
+export type L3Endpoint = Simplify<z.infer<typeof l3EndpointEntity.schema>>
+export type L4Endpoint = Simplify<z.infer<typeof l4EndpointEntity.schema>>
+export type L4Protocol = z.infer<typeof l4ProtocolSchema>
+export type L4PortInfo = z.infer<typeof l4PortInfoSchema>
+export type L7Endpoint = Simplify<z.infer<typeof l7EndpointEntity.schema>>
+export type L7AppInfo = z.infer<typeof l7AppInfoSchema>
+
+export type EndpointLevel = L3Endpoint["level"]
+
+export type EndpointByMinLevel<TMinLevel extends EndpointLevel> = {
+  3: L3Endpoint
+  4: L4Endpoint
+  7: L7Endpoint
+}[TMinLevel]

package/src/network/index.ts

@@ -0,0 +1,6 @@
+export * from "./address"
+export * from "./address-space"
+export * from "./dynamic-endpoint"
+export * from "./endpoint"
+export * from "./endpoint-schema"
+export * from "./subnet"

package/src/network/subnet.ts

@@ -0,0 +1,31 @@
+import { defineEntity, z } from "@highstate/contract"
+
+export type Subnet = z.infer<typeof subnetEntity.schema>
+export type AddressType = z.infer<typeof addressTypeSchema>
+
+export const addressTypeSchema = z.enum(["ipv4", "ipv6"])
+
+export const subnetEntity = defineEntity({
+  type: "network.subnet.v1",
+
+  schema: z.object({
+    /**
+     * The type of the subnet.
+     */
+    type: addressTypeSchema,
+
+    /**
+     * The canonical base IP address of the subnet.
+     */
+    baseAddress: z.string(),
+
+    /**
+     * The prefix length of the subnet.
+     */
+    prefixLength: z.number().int().nonnegative(),
+  }),
+
+  meta: {
+    color: "#3F51B5",
+  },
+})