@highstate/pulumi 0.18.0 → 0.20.0

package/src/entity.ts

@@ -0,0 +1,108 @@
+import {
+  type Entity,
+  type EntityMeta,
+  type EntityValue,
+  type EntityValueInput,
+  type EntityWithMeta,
+  getEntityId,
+  HighstateSignature,
+  type Secret,
+} from "@highstate/contract"
+import { type Input, type Output, output, type Unwrap } from "@pulumi/pulumi"
+import { type DeepInput, type InputArray, toPromise } from "./utils"
+
+export type MakeEntityOptions<TEntity extends Entity> = {
+  entity: TEntity
+  identity: string
+  meta?: Omit<EntityMeta, "type" | "identity">
+  value: Omit<EntityValueInput<TEntity>, "$meta">
+}
+
+export function makeEntity<TEntity extends Entity>({
+  entity,
+  identity,
+  meta,
+  value,
+}: MakeEntityOptions<TEntity>): EntityValue<TEntity> {
+  const built = {
+    ...(value as Record<string, unknown>),
+    $meta: {
+      type: entity.type,
+      identity,
+      ...meta,
+    },
+  }
+
+  return entity.schema.parse(built) as EntityValue<TEntity>
+}
+
+type CommonEntityMeta = Omit<EntityMeta, "type" | "identity">
+
+export type MakeEntityAsyncOptions<TEntity extends Entity> = {
+  entity: TEntity
+  identity: Input<string>
+  meta?: { [K in keyof CommonEntityMeta]?: Input<CommonEntityMeta[K]> }
+  value: {
+    [K in keyof Omit<EntityValueInput<TEntity>, "$meta">]: DeepInput<EntityValueInput<TEntity>[K]>
+  }
+}
+
+export function makeSecret<TValue>(value: TValue): Secret<TValue> {
+  return {
+    [HighstateSignature.Secret]: true,
+    value,
+  }
+}
+
+export function makeSecretOutput<TValue>(value: Input<TValue>): Output<Secret<Unwrap<TValue>>> {
+  return output(value).apply(makeSecret)
+}
+
+export function makeSecretAsync<TValue>(value: Input<TValue>): Promise<Secret<Unwrap<TValue>>> {
+  return toPromise(makeSecretOutput(value)) as Promise<Secret<Unwrap<TValue>>>
+}
+
+export function makeEntityOutput<TEntity extends Entity>({
+  entity,
+  identity,
+  meta,
+  value,
+}: MakeEntityAsyncOptions<TEntity>): Output<EntityValue<TEntity>> {
+  return output({
+    ...value,
+    $meta: {
+      type: entity.type,
+      identity,
+      ...meta,
+    },
+  }).apply(built => entity.schema.parse(built)) as Output<EntityValue<TEntity>>
+}
+
+export function makeEntityAsync<TEntity extends Entity>(
+  options: MakeEntityAsyncOptions<TEntity>,
+): Promise<EntityValue<TEntity>> {
+  return toPromise(makeEntityOutput(options)) as Promise<EntityValue<TEntity>>
+}
+
+export type IdentitySource = EntityWithMeta | string
+
+/**
+ * Get the combined identity based on the ids of the given entities.
+ *
+ * This function can be used for entities that do not have their own identity but are defined by the combination of other entities (e.g. a server defined by its network endpoints).
+ */
+export function getCombinedIdentity(entities: IdentitySource[]): string {
+  const sortedIds = entities
+    .map(source => (typeof source === "string" ? source : getEntityId(source)))
+    .sort() // sort to ensure consistent identity regardless of the order of entities
+
+  return sortedIds.join(":")
+}
+
+export function getCombinedIdentityOutput(entities: InputArray<IdentitySource>): Output<string> {
+  return output(entities).apply(getCombinedIdentity)
+}
+
+export function getCombinedIdentityAsync(entities: IdentitySource[]): Promise<string> {
+  return toPromise(getCombinedIdentityOutput(entities))
+}

package/src/file.ts

@@ -1,68 +1,106 @@
-import type { File } from "@highstate/contract"
-import { type Input, type Output, output, secret } from "@pulumi/pulumi"
+import type { EntityWithMeta, FileContent, FileMeta } from "@highstate/contract"
+import { crc32 } from "node:zlib"
+import { type Input, type Output, output, type Unwrap } from "@pulumi/pulumi"
+import { makeSecret } from "./entity"
+import { toPromise } from "./utils"
+
+/**
+ * The BaseFile is type that compatible with both the contract's File type and the file entity used in the library.
+ *
+ * It should be used in most places instead of the contract's File type to avoid unnecessary conversions, and it can be safely cast to the contract's File type when needed.
+ */
+export type BaseFile = EntityWithMeta & {
+  meta: FileMeta
+  content: FileContent
+}
 
 export type FileOptions = {
-  isSecret?: boolean
+  /**
+   * The name of the file.
+   */
+  name: Input<string>
+
+  /**
+   * The content of the file as a string or a buffer.
+   */
+  content: Input<string | Buffer>
+
+  /**
+   * The identity to use for the file entity.
+   *
+   * If not provided, defaults to the hash of the content.
+   */
+  identity?: Input<string>
+
+  /**
+   * Whether the content should be treated as a secret or not.
+   */
+  isSecret?: Input<boolean>
+
+  /**
+   * The content type of the file.
+   *
+   * Defaults to "text/plain" if the content is a string and "application/octet-stream" if the content is a buffer.
+   */
   contentType?: Input<string>
+
+  /**
+   * The file mode (permissions) to set on the file when materialized.
+   *
+   * Defaults to 0o644.
+   */
   mode?: Input<number>
 }
 
 /**
- * Creates a file from a string input.
- * This file can then be passed to terminals/pages or other components.
+ * Creates a file entity from the given options.
  *
- * @param name The name of the file.
- * @param content The content of the file.
- * @param options Additional options for the file.
+ * This file can also be used for both:
+ * - core Highstate capabilities like terminals and pages;
+ * - as inputs for other units requiring files.
  */
-export function fileFromString(
-  name: Input<string>,
-  content: Input<string>,
-  { contentType = "text/plain", isSecret = false, mode }: FileOptions = {},
-): Output<File> {
-  return output({
+export function makeFile({
+  name,
+  content,
+  contentType,
+  identity,
+  isSecret,
+  mode,
+}: Unwrap<FileOptions>): BaseFile {
+  const stringContent = typeof content === "string" ? content : content.toString("base64")
+  const isBinary = typeof content !== "string"
+  const inferredContentType =
+    contentType ?? (typeof content === "string" ? "text/plain" : "application/octet-stream")
+  const size =
+    typeof content === "string" ? Buffer.byteLength(content, "utf-8") : content.byteLength
+
+  return {
+    $meta: {
+      type: "common.file.v1",
+      identity: identity ?? crc32(stringContent).toString(16), // use crc32 hash of the content as the default identity
+    },
     meta: {
       name,
-      contentType,
-      size: output(content).apply(content => Buffer.byteLength(content, "utf8")),
+      contentType: inferredContentType,
+      size,
       mode,
     },
-    content: {
-      type: "embedded",
-      value: isSecret ? secret(content) : content,
-    },
-  })
+    content: isSecret
+      ? { type: "embedded-secret", value: makeSecret(stringContent), isBinary }
+      : { type: "embedded", value: stringContent, isBinary },
+  }
 }
 
 /**
- * Creates a file from a buffer input.
- * This file can then be passed to terminals/pages or other components.
- *
- * @param name The name of the file.
- * @param content The content of the file as a Buffer.
- * @param options Additional options for the file.
+ * Similar to `makeFile`, but returns a Pulumi Output that resolves to a file entity.
  */
-export function fileFromBuffer(
-  name: Input<string>,
-  content: Buffer,
-  { contentType = "application/octet-stream", isSecret = false, mode }: FileOptions = {},
-): Output<File> {
-  // const base64Content = output(content).apply(
-  // c => (console.log("fileFromBuffer", c), c.toString("base64")),
-  // )
-  const base64Content = content.toString("base64")
+export function makeFileOutput(options: FileOptions): Output<BaseFile> {
+  return output(options).apply(opts => makeFile(opts))
+}
 
-  return output({
-    meta: {
-      name,
-      contentType,
-      size: output(content).apply(content => content.byteLength),
-      mode,
-    },
-    content: {
-      type: "embedded",
-      isBinary: true,
-      value: isSecret ? secret(base64Content) : base64Content,
-    },
-  })
+/**
+ * Similar to `makeFile`, but returns a Promise that resolves to a file entity.
+ */
+export function makeFileAsync(options: FileOptions): Promise<BaseFile> {
+  return toPromise(makeFileOutput(options))
 }

package/src/index.ts

@@ -1,4 +1,6 @@
 export * from "@pulumi/pulumi"
+export * from "./entity"
 export * from "./file"
+export * from "./resource-hooks"
 export * from "./unit"
 export * from "./utils"

package/src/resource-hooks.ts

@@ -0,0 +1,14 @@
+let hasResourceHooks = false
+
+/**
+ * Marks the current Pulumi program as using resource hooks.
+ *
+ * The backend uses `$hasResourceHooks` output to decide whether it should run the Pulumi program on destroy.
+ */
+export function setResourceHooks(): void {
+  hasResourceHooks = true
+}
+
+export function getHasResourceHooks(): boolean {
+  return hasResourceHooks
+}