@sst-community/sst 4.21.1 → 5.0.0-alpha.2

package/platform/src/components/parts.ts

@@ -0,0 +1,299 @@
+import type { CustomResourceOptions, Input, Output } from "@pulumi/pulumi";
+import type { PartTransform, PartialArgs } from "./transform";
+
+/**
+ * The resources a component is made of, by name. Each one is the class of a
+ * Pulumi resource or of another component.
+ *
+ * ```ts
+ * const parts = {
+ *   queue: aws.sqs.Queue,
+ *   policy: aws.sqs.QueuePolicy,
+ * };
+ * ```
+ *
+ * Inside SST, a part that is another component has to be declared in a
+ * function, `const parts = () => ({ ... })`. The components import each
+ * other, so the class may not exist yet when the file that declares the parts
+ * loads.
+ */
+export type Parts = Record<string, UnnamedPart | NamedPart>;
+
+type UnnamedPart = PartClass | DeferredPart | ManyPart | OptionalPart;
+
+export type PartClass = new (name: string, args: any, opts?: any) => any;
+
+/** A part declared with `deferred()`. */
+export interface DeferredPart<C extends PartClass = PartClass> {
+  deferred: C;
+}
+
+/**
+ * Declare a part that is created later, or not at all. A subscriber's
+ * function is one: it's created once the definition is known, and it isn't
+ * created when the user passes the ARN of a function they already have.
+ *
+ * The part's entry in `nodes` is an `Output` of the resource. Create the
+ * function with `functionPart()`.
+ *
+ * ```ts
+ * const parts = () => ({
+ *   subscriber: deferred(Function),
+ *   eventSourceMapping: aws.lambda.EventSourceMapping,
+ * });
+ *
+ * functionPart(this, "subscriber", "src/subscriber.handler", {});
+ * ```
+ */
+export function deferred<C extends PartClass>(cls: C): DeferredPart<C> {
+  return { deferred: cls };
+}
+
+/** A part declared with `optional()`. */
+export interface OptionalPart<C extends PartClass = PartClass> {
+  optional: C;
+}
+
+/**
+ * Declare a part the component only creates sometimes, like a dead-letter
+ * queue that exists only when it's configured. Its entry in `nodes` may be
+ * `undefined`.
+ *
+ * ```ts
+ * const parts = {
+ *   queue: aws.sqs.Queue,
+ *   deadLetters: optional(aws.sqs.Queue),
+ * };
+ * ```
+ */
+export function optional<C extends PartClass>(cls: C): OptionalPart<C> {
+  return { optional: cls };
+}
+
+/** A part declared with `many()`. */
+export interface ManyPart<
+  T extends PartClass | DeferredPart = PartClass | DeferredPart,
+> {
+  many: T;
+}
+
+/**
+ * Declare a part the component creates several of, like one subnet per zone
+ * or one listener per port. Each one is created with an id:
+ *
+ * ```ts
+ * const parts = {
+ *   vpc: aws.ec2.Vpc,
+ *   subnet: many(aws.ec2.Subnet),
+ * };
+ *
+ * this.part("subnet", "1", { ... }); // named MyVpcSubnet1
+ * this.part("subnet", "2", { ... }); // named MyVpcSubnet2
+ * ```
+ *
+ * The part's `transform` applies to each one; its function form is also given
+ * the id. Its entry in `nodes` holds them by id.
+ *
+ * Wrap a deferred part to have several of those, like one function per
+ * subscriber: `many(deferred(Function))`.
+ */
+export function many<T extends PartClass | DeferredPart>(part: T): ManyPart<T> {
+  return { many: part };
+}
+
+/** A part declared with `named()`. */
+export interface NamedPart<T extends UnnamedPart = UnnamedPart> {
+  named: string;
+  part: T;
+}
+
+/**
+ * Declare a part whose resource isn't named after its key. A resource is
+ * named after the component and the part, `MyQueue` and `policy` giving
+ * `MyQueuePolicy`, and that name is how a deployed app knows the resource.
+ * With `named()` the key can change, or differ from the name, and the
+ * resource stays the one that's deployed:
+ *
+ * ```ts
+ * const parts = {
+ *   // Named MyVpcNatInstanceSecurityGroup
+ *   natSecurityGroup: named(aws.ec2.SecurityGroup, "NatInstanceSecurityGroup"),
+ * };
+ * ```
+ *
+ * It wraps the other markers: `named(optional(aws.ec2.SecurityGroup), "...")`.
+ * For a `many()` part the id is added to the name, as it is to the key.
+ *
+ * The name is permanent. Changing it later renames the resource, which
+ * replaces it unless it's given an alias.
+ */
+export function named<T extends UnnamedPart>(part: T, name: string): NamedPart<T> {
+  return { named: name, part };
+}
+
+/** A part as it's declared, without the name `named()` gives it. */
+export type Unnamed<T> = T extends NamedPart<infer U> ? U : T;
+
+export type PartClassOf<T> =
+  T extends NamedPart<infer U>
+    ? PartClassOf<U>
+    : T extends DeferredPart<infer C>
+      ? C
+      : T extends ManyPart<infer M>
+        ? PartClassOf<M>
+        : T extends OptionalPart<infer C>
+          ? C
+          : T extends PartClass
+            ? T
+            : never;
+
+function unnamed(part: Parts[string]): UnnamedPart {
+  return typeof part !== "function" && "named" in part ? part.part : part;
+}
+
+export function partClass(part: Parts[string] | DeferredPart): PartClass {
+  const declared = unnamed(part);
+  if (typeof declared === "function") return declared;
+  if ("many" in declared) return partClass(declared.many);
+  return "optional" in declared ? declared.optional : declared.deferred;
+}
+
+/** Whether a part's resources are created later, or not at all. */
+export function isDeferred(part: Parts[string] | DeferredPart): boolean {
+  const declared = unnamed(part);
+  if (typeof declared === "function") return false;
+  return "many" in declared ? isDeferred(declared.many) : "deferred" in declared;
+}
+
+export function isMany(part: Parts[string]): boolean {
+  const declared = unnamed(part);
+  return typeof declared !== "function" && "many" in declared;
+}
+
+/** The name a part was given with `named()`, in place of its key. */
+export function nameGiven(part: Parts[string]): string | undefined {
+  return typeof part !== "function" && "named" in part ? part.named : undefined;
+}
+
+/** The args a part's resource is created with. */
+export type PartArgs<T extends Parts[string]> = NonNullable<
+  ConstructorParameters<PartClassOf<T>>[1]
+>;
+
+/**
+ * The transform for a part the component creates several of. The function
+ * form is called for each one, with its id as the last argument.
+ */
+export type ManyTransform<T> =
+  | PartialArgs<T>
+  | ((
+      args: T,
+      opts: CustomResourceOptions,
+      name: string,
+      id: string,
+    ) => undefined);
+
+/** The `transform` option for a component: one optional transform per part. */
+export type Transforms<P extends Parts> = {
+  [K in keyof P]?: Unnamed<P[K]> extends ManyPart
+    ? ManyTransform<PartArgs<P[K]>>
+    : PartTransform<PartArgs<P[K]>>;
+};
+
+/**
+ * The `nodes` of a component: the resource created for each part. A deferred
+ * part is an `Output` of its resource, and a `many` part holds its resources
+ * by id.
+ */
+export type Nodes<P extends Parts> = {
+  [K in keyof P]: Unnamed<P[K]> extends DeferredPart<infer C>
+    ? Output<InstanceType<C>>
+    : Unnamed<P[K]> extends ManyPart<infer M>
+      ? Record<
+          string,
+          M extends DeferredPart<infer C>
+            ? Output<InstanceType<C>>
+            : InstanceType<PartClassOf<M>>
+        >
+      : Unnamed<P[K]> extends OptionalPart<infer C>
+        ? InstanceType<C> | undefined
+        : InstanceType<PartClassOf<P[K]>>;
+};
+
+/**
+ * The `existing` option for a component: resources to use in place of ones
+ * the component would create. Each is the resource itself, or the id to look
+ * it up by. A `many` part takes them by id.
+ */
+export type Existing<P extends Parts> = {
+  [K in keyof P]?: Unnamed<P[K]> extends ManyPart
+    ? Record<string, InstanceType<PartClassOf<P[K]>> | Input<string>>
+    : InstanceType<PartClassOf<P[K]>> | Input<string>;
+};
+
+/** A parts map, or the function that returns it. */
+type PartsOf<T> = T extends () => infer P ? P : T;
+
+// The args of a V5 component that takes the same args as the component it
+// replaces: the original's args, with `transform` and `existing` for the new
+// component's parts.
+//
+//   interface QueueV5Args extends V5Args<QueueArgs, typeof parts> {}
+//
+// (Not a doc comment: an interface that extends this would show it as its own
+// description in the generated docs.)
+export type V5Args<Original, P extends Parts | (() => Parts)> = Omit<
+  Original,
+  "transform"
+> &
+  ComponentArgs<P>;
+
+/**
+ * The args every component built from parts accepts. Extend it in your
+ * component's args.
+ *
+ * ```ts
+ * interface UploadsArgs extends sst.ComponentArgs<typeof parts> {
+ *   teams: string[];
+ * }
+ * ```
+ */
+export interface ComponentArgs<P extends Parts | (() => Parts)> {
+  /**
+   * [Transform](/docs/components#transform) how this component creates its underlying
+   * resources.
+   */
+  transform?: Transforms<PartsOf<P>>;
+  /**
+   * Use resources you already have in place of ones this component would
+   * create. Pass the resource, or the id to look it up by.
+   *
+   * @example
+   * ```ts
+   * {
+   *   existing: {
+   *     queue: "https://sqs.us-east-1.amazonaws.com/123456789012/my-queue"
+   *   }
+   * }
+   * ```
+   */
+  existing?: Existing<PartsOf<P>>;
+}
+
+export type ManyKeys<P extends Parts> = {
+  [K in keyof P]: Unnamed<P[K]> extends ManyPart ? K : never;
+}[keyof P] &
+  string;
+
+export type SingleKeys<P extends Parts> = Exclude<keyof P & string, ManyKeys<P>>;
+
+/**
+ * The parts `this.part()` creates. A deferred part is left out: it's created
+ * with `functionPart()`, which makes its `nodes` entry an `Output`.
+ */
+export type CreatedKeys<P extends Parts> = {
+  [K in keyof P]: Unnamed<P[K]> extends DeferredPart | ManyPart<DeferredPart>
+    ? never
+    : K;
+}[keyof P] &
+  string;

package/platform/src/components/path.ts

@@ -0,0 +1,5 @@
+import path from "path";
+
+export function toPosix(p: string) {
+  return p.split(path.sep).join(path.posix.sep);
+}

package/platform/src/components/rpc/rpc.ts

@@ -0,0 +1,110 @@
+import { dynamic } from "@pulumi/pulumi";
+import http from "http";
+
+export namespace rpc {
+  export class MethodNotFoundError extends Error {
+    constructor(public method: string) {
+      super(`Method "${method}" not found`);
+    }
+  }
+  export async function call<T = any>(method: string, args: any) {
+    return new Promise<T>((resolve, reject) => {
+      const url = new URL(process.env.SST_SERVER! + "/rpc");
+      const options = {
+        hostname: url.hostname,
+        port: url.port,
+        path: url.pathname,
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+      };
+
+      const req = http.request(options, (res) => {
+        let data = "";
+
+        res.on("data", (chunk) => {
+          data += chunk;
+        });
+
+        res.on("end", () => {
+          if (res.statusCode !== 200) {
+            reject(new Error(`Failed to call RPC: ${data}`));
+            return;
+          }
+          try {
+            const json = JSON.parse(data);
+            if (json.error) {
+              if (json.error.startsWith("rpc: can't find")) {
+                reject(new MethodNotFoundError(method));
+                return;
+              }
+              reject(new Error(json.error));
+              return;
+            }
+            resolve(json.result);
+          } catch (error: any) {
+            reject(new Error(`Failed to parse JSON: ${error.message}`));
+          }
+        });
+      });
+
+      req.on("error", (error) => {
+        reject(error);
+      });
+
+      // Set timeout to 0 to prevent any timeout
+      req.setTimeout(0);
+
+      const body = JSON.stringify({
+        jsonrpc: "1.0",
+        method,
+        params: [args],
+      });
+
+      req.write(body);
+      req.end();
+    });
+  }
+
+  export class Provider implements dynamic.ResourceProvider {
+    constructor(private type: string) {}
+    private name(action: string) {
+      return "Resource." + this.type + "." + action;
+    }
+    async create(inputs: any) {
+      return call(this.name("Create"), inputs) as Promise<dynamic.CreateResult>;
+    }
+
+    async delete(id: string, outs: any): Promise<void> {
+      return call(this.name("Delete"), { id, outs }).catch((ex) => {
+        if (ex instanceof MethodNotFoundError) return;
+        throw ex;
+      });
+    }
+
+    async update(id: string, olds: any, news: any) {
+      return call(this.name("Update"), { id, olds, news }).catch((ex) => {
+        if (ex instanceof MethodNotFoundError)
+          return {
+            id,
+          };
+        throw ex;
+      });
+    }
+
+    async read(id: string, props: any): Promise<dynamic.ReadResult> {
+      return call(this.name("Read"), { id, props }).catch((ex) => {
+        if (ex instanceof MethodNotFoundError) return { id, props };
+        throw ex;
+      });
+    }
+
+    async diff(id: string, olds: any, news: any): Promise<dynamic.DiffResult> {
+      return call(this.name("Diff"), { id, olds, news }).catch((ex) => {
+        if (ex instanceof MethodNotFoundError) return { id, olds, news };
+        throw ex;
+      });
+    }
+  }
+}

package/platform/src/components/secret.ts

@@ -0,0 +1,159 @@
+import { VisibleError } from "./error";
+import { Output, output, secret } from "@pulumi/pulumi";
+import { Link } from "./link";
+import { Component, Prettify } from "./component";
+import { Input } from "./input";
+
+export class SecretMissingError extends VisibleError {
+  constructor(public readonly secretName: string) {
+    super(
+      `Set a value for ${secretName} with \`sst secret set ${secretName} <value>\``,
+    );
+  }
+}
+
+/**
+ * The `Secret` component lets you create secrets in your app.
+ *
+ * Secrets are encrypted and stored in an S3 Bucket in your AWS account. If used in
+ * your app config, they'll be encrypted in your state file as well. If used in
+ * your function code, they are encrypted and included in the bundle. They are
+ * then decrypted synchronously when your function starts up by the SST SDK.
+ *
+ * @example
+ *
+ * #### Create a secret
+ *
+ * The name of a secret follows the same rules as a component name. It must start with a capital letter and contain only letters and numbers.
+ *
+ * :::note
+ * Secret names must start with a capital letter and contain only letters and numbers.
+ * :::
+ *
+ * ```ts title="sst.config.ts"
+ * const secret = new sst.Secret("MySecret");
+ * ```
+ *
+ * #### Set a placeholder
+ *
+ * You can optionally set a `placeholder`.
+ *
+ * :::tip
+ * Useful for cases where you might use a secret for values that aren't sensitive, so you can just set them in code.
+ * :::
+ *
+ * ```ts title="sst.config.ts"
+ * const secret = new sst.Secret("MySecret", "my-secret-placeholder-value");
+ * ```
+ *
+ * #### Set the value of the secret
+ *
+ * You can then set the value of a secret using the [CLI](/docs/reference/cli/).
+ *
+ * ```sh title="Terminal"
+ * sst secret set MySecret my-secret-value
+ * ```
+ *
+ * :::note
+ * If you are not running `sst dev`, you'll need to `sst deploy` to apply the secret.
+ * :::
+ *
+ * #### Set a fallback for the secret
+ *
+ * You can set a _fallback_ value for the secret with the `--fallback` flag. If the secret is
+ * not set for a stage, it'll use the fallback value instead.
+ *
+ * ```sh title="Terminal"
+ * sst secret set MySecret my-fallback-value --fallback
+ * ```
+ *
+ * This is useful for PR environments that are auto-deployed.
+ *
+ * #### Use the secret in your app config
+ *
+ * You can now use the secret in your app config.
+ *
+ * ```ts title="sst.config.ts"
+ * console.log(mySecret.value);
+ * ```
+ *
+ * This is an [Output](/docs/components#outputs) that can be used as an Input to other components.
+ *
+ * #### Link the secret to a resource
+ *
+ * You can link the secret to other resources, like a function or your Next.js app.
+ *
+ * ```ts title="sst.config.ts"
+ * new sst.aws.Nextjs("MyWeb", {
+ *   link: [secret]
+ * });
+ * ```
+ *
+ * Once linked, you can use the secret in your function code.
+ *
+ * ```ts title="app/page.tsx"
+ * import { Resource } from "sst";
+ *
+ * console.log(Resource.MySecret.value);
+ * ```
+ */
+export class Secret extends Component implements Link.Linkable {
+  private _value: Output<string>;
+  private _name: string;
+  private _placeholder?: Output<string>;
+
+  /**
+   * @param placeholder A placeholder value of the secret. This can be useful for cases where you might not be storing sensitive values.
+
+   */
+  constructor(name: string, placeholder?: Input<string>) {
+    super(
+      "sst:sst:Secret",
+      name,
+      {
+        placeholder,
+      },
+      {},
+    );
+    this._name = name;
+    this._placeholder = placeholder !== undefined ? output(placeholder) : undefined;
+    this._value = output(
+      process.env["SST_SECRET_" + this._name] ?? this._placeholder,
+    ).apply((value) => {
+      if (typeof value !== "string") {
+        throw new SecretMissingError(this._name);
+      }
+      return value;
+    });
+  }
+
+  /**
+   * The name of the secret.
+   */
+  public get name() {
+    return output(this._name);
+  }
+
+  /**
+   * The value of the secret. It'll be `undefined` if the secret has not been set through the CLI or if the `placeholder` hasn't been set.
+   */
+  public get value() {
+    return secret(this._value);
+  }
+
+  /**
+   * The placeholder value of the secret.
+   */
+  public get placeholder() {
+    return this._placeholder;
+  }
+
+  /** @internal */
+  public getSSTLink() {
+    return {
+      properties: {
+        value: this.value,
+      },
+    };
+  }
+}

package/platform/src/components/size.ts

@@ -0,0 +1,28 @@
+export type Size = `${number} ${"MB" | "GB"}`;
+export type SizeGbTb = `${number} ${"GB" | "TB"}`;
+
+export function toMBs(size: Size | SizeGbTb) {
+  const [count, unit] = size.split(" ");
+  const countNum = parseFloat(count);
+  if (unit === "MB") {
+    return countNum;
+  } else if (unit === "GB") {
+    return countNum * 1024;
+  } else if (unit === "TB") {
+    return countNum * 1024 * 1024;
+  }
+  throw new Error(`Invalid size ${size}`);
+}
+
+export function toGBs(size: Size | SizeGbTb) {
+  const [count, unit] = size.split(" ");
+  const countNum = parseFloat(count);
+  if (unit === "MB") {
+    return countNum / 1024;
+  } else if (unit === "GB") {
+    return countNum;
+  } else if (unit === "TB") {
+    return countNum * 1024;
+  }
+  throw new Error(`Invalid size ${size}`);
+}