@highstate/common 0.9.16 → 0.9.19

package/src/shared/impl-ref.ts

@@ -0,0 +1,123 @@
+import type { ImplementationReference } from "@highstate/library"
+import type { z } from "@highstate/contract"
+import { type Output, output, toPromise, type Input, type Unwrap } from "@highstate/pulumi"
+
+/**
+ * The ImplementationMediator is used as a contract between the calling code and the implementation.
+ *
+ * From the calling code perspective, it provides a way to define the input and output schemas for the implementation
+ * and call the implementation with the provided input.
+ *
+ * From the implementation perspective, it provides a way to get zod function with automatic type inference and validation.
+ */
+export class ImplementationMediator<
+  TInputSchema extends z.ZodType,
+  TOutputSchema extends z.ZodType,
+> {
+  constructor(
+    readonly path: string,
+    private readonly inputSchema: TInputSchema,
+    private readonly outputSchema: TOutputSchema,
+  ) {}
+
+  implement<TDataSchema extends z.ZodType>(
+    dataSchema: TDataSchema,
+    func: (
+      input: z.infer<TInputSchema>,
+      data: z.infer<TDataSchema>,
+    ) => z.infer<TOutputSchema> | Promise<z.infer<TOutputSchema>>,
+  ) {
+    return async (
+      input: z.infer<TInputSchema>,
+      data: z.infer<TDataSchema>,
+    ): Promise<z.infer<TOutputSchema>> => {
+      const parsedInput = this.inputSchema.safeParse(input)
+      if (!parsedInput.success) {
+        throw new Error(
+          `Invalid input for implementation "${this.path}": ${parsedInput.error.message}`,
+        )
+      }
+
+      const parsedData = dataSchema.safeParse(data)
+      if (!parsedData.success) {
+        throw new Error(
+          `Invalid data for implementation "${this.path}": ${parsedData.error.message}`,
+        )
+      }
+
+      const result = await func(parsedInput.data, parsedData.data)
+      const parsedResult = this.outputSchema.safeParse(result)
+
+      if (!parsedResult.success) {
+        throw new Error(
+          `Invalid output from implementation "${this.path}": ${parsedResult.error.message}`,
+        )
+      }
+
+      return parsedResult.data
+    }
+  }
+
+  async call(
+    implRef: Input<ImplementationReference>,
+    input: Input<z.infer<TInputSchema>>,
+  ): Promise<z.infer<TOutputSchema>> {
+    const resolvedImplRef = await toPromise(implRef)
+    const resolvedInput = await toPromise(input)
+
+    const importPath = `${resolvedImplRef.package}/impl/${this.path}`
+
+    let impl: Record<string, unknown>
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      impl = await import(importPath)
+    } catch (error) {
+      throw new Error(`Failed to import module "${importPath}" required by implementation.`, {
+        cause: error,
+      })
+    }
+
+    const funcs = Object.entries(impl).filter(value => typeof value[1] === "function") as [
+      string,
+      Function,
+    ][]
+
+    if (funcs.length === 0) {
+      throw new Error(`No implementation functions found in module "${importPath}".`)
+    }
+
+    if (funcs.length > 1) {
+      throw new Error(
+        `Multiple implementation functions found in module "${importPath}": ${funcs.map(func => func[0]).join(", ")}. ` +
+          "Ensure only one function is exported.",
+      )
+    }
+
+    const [funcName, implFunc] = funcs[0]
+
+    let result: unknown
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      result = await implFunc(resolvedInput, resolvedImplRef.data)
+    } catch (error) {
+      console.error(`Error in implementation function "${funcName}":`, error)
+      throw new Error(`Implementation function "${funcName}" failed`)
+    }
+
+    const parsedResult = this.outputSchema.safeParse(result)
+    if (!parsedResult.success) {
+      throw new Error(
+        `Implementation function "${funcName}" returned invalid result: ${parsedResult.error.message}`,
+      )
+    }
+
+    return parsedResult.data
+  }
+
+  callOutput(
+    implRef: Input<ImplementationReference>,
+    input: Input<z.infer<TInputSchema>>,
+  ): Output<Unwrap<z.infer<TOutputSchema>>> {
+    return output(this.call(implRef, input))
+  }
+}

package/src/shared/index.ts

@@ -4,3 +4,7 @@ export * from "./passwords"
 export * from "./ssh"
 export * from "./network"
 export * from "./files"
+export * from "./impl-ref"
+export * from "./gateway"
+export * from "./tls"
+export * from "./access-point"

package/src/shared/network.ts

@@ -1,5 +1,5 @@
 import type { ArrayPatchMode, network } from "@highstate/library"
-import { toPromise, type Input } from "@highstate/pulumi"
+import { type Input, toPromise } from "@highstate/pulumi"
 import { uniqueBy } from "remeda"
 
 /**
@@ -248,14 +248,14 @@ export async function requireInputL4Endpoint(
 }
 
 /**
- * Convers L3 endpoint to L4 endpoint by adding a port and protocol.
+ * Converts L3 endpoint to L4 endpoint by adding a port and protocol.
  *
  * @param l3Endpoint The L3 endpoint to convert.
  * @param port The port to add to the L3 endpoint.
  * @param protocol The protocol to add to the L3 endpoint. Defaults to "tcp".
  * @returns The L4 endpoint with the port and protocol added.
  */
-export function l3ToL4Endpoint(
+export function l3EndpointToL4(
   l3Endpoint: InputL3Endpoint,
   port: number,
   protocol: network.L4Protocol = "tcp",
@@ -276,11 +276,14 @@ export function l3ToL4Endpoint(
  *
  * @returns The filtered list of endpoints.
  */
-export function filterEndpoints<TEndpoint extends network.L34Endpoint>(
+export function filterEndpoints<
+  TEndpoint extends network.L34Endpoint,
+  TType extends network.L34Endpoint["type"],
+>(
   endpoints: TEndpoint[],
   filter?: network.EndpointFilter,
-  types?: network.L34Endpoint["type"][],
-): TEndpoint[] {
+  types?: TType[],
+): (TEndpoint & { type: TType })[] {
   if (filter?.length) {
     endpoints = endpoints.filter(endpoint => filter.includes(endpoint.visibility))
   } else if (endpoints.some(endpoint => endpoint.visibility === "public")) {
@@ -289,11 +292,11 @@ export function filterEndpoints<TEndpoint extends network.L34Endpoint>(
     endpoints = endpoints.filter(endpoint => endpoint.visibility === "external")
   }
 
-  if (types && types.length) {
-    endpoints = endpoints.filter(endpoint => types.includes(endpoint.type))
+  if (types?.length) {
+    endpoints = endpoints.filter(endpoint => types.includes(endpoint.type as TType))
   }
 
-  return endpoints
+  return endpoints as (TEndpoint & { type: TType })[]
 }
 
 /**
@@ -369,31 +372,42 @@ export function parseL7Endpoint(l7Endpoint: InputL7Endpoint): network.L7Endpoint
  * @param endpoints The new endpoints to add in string format.
  * @param inputEndpoints The input endpoints to add in object format.
  * @param mode The mode to use when updating the endpoints. Can be "replace" or "prepend". Defaults to "prepend".
- *
- * @returns The updated list of endpoints.
+ * @returns The updated list of endpoints with duplicates removed.
  */
-export async function updateEndpoints<TEdnpoints extends network.L34Endpoint>(
-  currentEndpoints: Input<TEdnpoints[]>,
-  endpoints: string[],
-  inputEndpoints: Input<TEdnpoints[]>,
+export async function updateEndpoints<TEndpoints extends network.L34Endpoint>(
+  currentEndpoints: Input<TEndpoints[]>,
+  endpoints: string[] | undefined,
+  inputEndpoints: Input<TEndpoints[]> | undefined,
   mode: ArrayPatchMode = "prepend",
-): Promise<TEdnpoints[]> {
+): Promise<TEndpoints[]> {
   const resolvedCurrentEndpoints = await toPromise(currentEndpoints)
-  const resolvedInputEndpoints = await toPromise(inputEndpoints)
-
-  const newEndpoints = uniqueBy(
-    //
-    [...endpoints.map(parseL34Endpoint), ...resolvedInputEndpoints],
-    endpoint => l34EndpointToString(endpoint),
-  )
+  const newEndpoints = await parseEndpoints(endpoints, inputEndpoints)
 
   if (mode === "replace") {
-    return newEndpoints as TEdnpoints[]
+    return newEndpoints as TEndpoints[]
   }
 
   return uniqueBy(
-    //
     [...newEndpoints, ...resolvedCurrentEndpoints],
-    endpoint => l34EndpointToString(endpoint),
-  ) as TEdnpoints[]
+    l34EndpointToString,
+  ) as TEndpoints[]
+}
+
+/**
+ * Parses a list of endpoints from strings and input objects.
+ *
+ * @param endpoints The list of endpoint strings to parse.
+ * @param inputEndpoints The list of input endpoint objects to use.
+ * @returns The parsed list of endpoint objects with duplicates removed.
+ */
+export async function parseEndpoints<TEndpoints extends network.L34Endpoint>(
+  endpoints: string[] | undefined,
+  inputEndpoints: Input<TEndpoints[]> | undefined,
+): Promise<TEndpoints[]> {
+  const resolvedInputEndpoints = await toPromise(inputEndpoints)
+
+  return uniqueBy(
+    [...(endpoints?.map(parseL34Endpoint) ?? []), ...(resolvedInputEndpoints ?? [])],
+    l34EndpointToString,
+  ) as TEndpoints[]
 }

package/src/shared/passwords.ts

@@ -1,6 +1,42 @@
-import { randomBytes } from "@noble/hashes/utils"
+import { bytesToHex, randomBytes } from "@noble/hashes/utils"
 import { secureMask } from "micro-key-producer/password.js"
 
-export function generatePassword() {
+/**
+ * Generates a secure random password strong enough for online use.
+ *
+ * It uses "Safari Keychain Secure Password" format.
+ *
+ * The approximate entropy is [71 bits](https://support.apple.com/guide/security/automatic-strong-passwords-secc84c811c4/web).
+ */
+export function generatePassword(): string {
   return secureMask.apply(randomBytes(32)).password
 }
+
+type KeyFormatMap = {
+  raw: Uint8Array
+  hex: string
+  base64: string
+}
+
+/**
+ * Generates a secure random key strong enough for offline use such as encryption.
+ *
+ * The strong entropy is 256 bits.
+ *
+ * @param format The format of the generated key. By default, it is "hex".
+ */
+export function generateKey<TFormat extends keyof KeyFormatMap = "hex">(
+  format: TFormat = "hex" as TFormat,
+): KeyFormatMap[TFormat] {
+  const bytes = randomBytes(32)
+
+  if (format === "raw") {
+    return bytes as KeyFormatMap[TFormat]
+  }
+
+  if (format === "base64") {
+    return Buffer.from(bytes).toString("base64") as KeyFormatMap[TFormat]
+  }
+
+  return bytesToHex(bytes) as KeyFormatMap[TFormat]
+}