sailfork / t3code-github / .repos/ alchemy-effect/ packages/ fly/ src/ Bucket.ts

import type { AddOnsResponseEdgesItemNode } from "@distilled.cloud/fly-io/addons";
import * as addons from "@distilled.cloud/fly-io/addons";
import * as machines from "@distilled.cloud/fly-io/machines";
import { Unowned } from "alchemy/AdoptPolicy";
import { deepEqual, isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as Result from "effect/Result";
import * as Schedule from "effect/Schedule";
import { resolveOrgSlug } from "./Environment.ts";
import { TigrisCredentialsMissing } from "./Errors.ts";
import { createFlyAppName, matchesAlchemyPhysicalName } from "./Metadata.ts";
import type { Providers } from "./Providers.ts";

/** Env-var names Tigris HTTP bindings write onto an App (same as `fly storage create`). */
export const BUCKET_SECRET_NAMES = [
  "AWS_ACCESS_KEY_ID",
  "AWS_SECRET_ACCESS_KEY",
  "AWS_ENDPOINT_URL_S3",
  "AWS_REGION",
  "BUCKET_NAME",
] as const;

export type BucketSecretName = (typeof BUCKET_SECRET_NAMES)[number];

/**
 * Shadow bucket used to migrate from another S3-compatible store.
 * Every field is required when set.
 */
export interface BucketShadow {
  /** Shadow-bucket access key id. */
  accessKey: string;
  /** Shadow-bucket secret. Wrap with `Redacted.make`. */
  secretKey: Redacted.Redacted<string> | string;
  /** Shadow-bucket region. */
  region: string;
  /** Shadow-bucket name. */
  name: string;
  /** Shadow-bucket S3 endpoint URL. */
  endpoint: string;
  /**
   * Dual-write new objects back to the shadow bucket.
   *
   * @default false
   */
  writeThrough?: boolean;
}

export interface BucketProps {
  /**
   * Tigris bucket / add-on name. Globally unique, DNS-compatible
   * (lowercase letters, digits, hyphens), must start with a letter,
   * max 63 characters. If omitted, a unique name is generated from
   * the stack, stage and logical ID. Changing it replaces the Bucket.
   */
  name?: string;
  /**
   * Organization slug. Defaults to the current token's org
   * (`getCurrentToken`). Changing it replaces the Bucket.
   */
  orgSlug?: string;
  /**
   * Serve objects without credentials. Default is private.
   *
   * @default false
   */
  public?: boolean;
  /**
   * Custom domain for public website hosting. Maps to Tigris
   * `options.website.domain_name`. Empty string when omitted
   * (the Tigris API requires the field).
   */
  domainName?: string;
  /**
   * Tigris accelerate. Default is off.
   *
   * @default false
   */
  accelerate?: boolean;
  /**
   * Shadow bucket for zero-downtime migration from another
   * S3-compatible store. Every nested field is required when set.
   */
  shadowBucket?: BucketShadow;
}

export type Bucket = Resource<
  "Fly.Bucket",
  BucketProps,
  {
    /** Fly GraphQL add-on id. Identity of the Bucket. */
    addOnId: string;
    /** Physical Tigris add-on / bucket name. */
    name: string;
    /** Observed provisioning status (`ready`, …). */
    status: string | undefined;
    /** Organization slug. */
    orgSlug: string | undefined;
    /** Whether the bucket is public. */
    public: boolean;
    /** Custom website domain, if set. */
    domainName: string | undefined;
    /** Tigris accelerate. */
    accelerate: boolean;
    /** Tigris SSO dashboard URL, if the API returned one. */
    ssoLink: string | undefined;
    /** RFC3339 creation timestamp. */
    createdAt: string | undefined;
    /**
     * `AWS_ACCESS_KEY_ID` from `createAddOn.environment`. Never logged.
     */
    accessKeyId: Redacted.Redacted<string> | undefined;
    /**
     * `AWS_SECRET_ACCESS_KEY` from `createAddOn.environment`. Never logged.
     */
    secretAccessKey: Redacted.Redacted<string> | undefined;
    /**
     * `AWS_ENDPOINT_URL_S3` from `createAddOn.environment`. Never logged.
     */
    endpoint: Redacted.Redacted<string> | undefined;
    /**
     * `AWS_REGION` from `createAddOn.environment`. Never logged.
     */
    region: Redacted.Redacted<string> | undefined;
    /**
     * `BUCKET_NAME` from `createAddOn.environment`. Never logged.
     */
    bucketName: Redacted.Redacted<string> | undefined;
  },
  never,
  Providers
>;

/**
 * A Fly.Bucket is Tigris S3-compatible object storage, billed through
 * Fly. It is an org-scoped GraphQL add-on (`AddOnType` `tigris`).
 *
 * @see https://fly.io/docs/tigris/
 *
 * ### Create a Bucket
 * Alchemy generates a unique name unless you pass one.
 *
 * **Example:** Generated name
 * ```typescript
 * const data = yield* Fly.Bucket("Data");
 * ```
 *
 * ### A stable name
 * Pass `name` when you need a stable Tigris bucket name.
 *
 * **Example:** Explicit name
 * ```typescript
 * const data = yield* Fly.Bucket("Data", {
 *   name: "my-bucket",
 * });
 * ```
 *
 * :::caution[Changing `name` replaces the Bucket]
 * Tigris cannot rename a bucket. Alchemy creates the new name, then
 * deletes the old one.
 * :::
 *
 * ### Organization
 * Org defaults to the current token. Pass `orgSlug` to pin it.
 *
 * **Example:** Pin an org
 * ```typescript
 * const data = yield* Fly.Bucket("Data", {
 *   orgSlug: "my-org",
 * });
 * ```
 *
 * :::caution[Changing `orgSlug` replaces the Bucket]
 * The bucket is created in the new org. The old bucket is deleted.
 * :::
 *
 * ### Public access
 * Buckets are private by default. `public: true` serves objects
 * without credentials.
 *
 * **Example:** Public bucket
 * ```typescript
 * const assets = yield* Fly.Bucket("Assets", {
 *   public: true,
 * });
 * ```
 *
 * ### Custom domain
 * `domainName` sets `website.domain_name` on the add-on. Point a
 * CNAME at `{name}.t3.tigrisbucket.io`.
 *
 * **Example:** Custom domain
 * ```typescript
 * const assets = yield* Fly.Bucket("Assets", {
 *   public: true,
 *   domainName: "assets.example.com",
 * });
 * ```
 *
 * ### Put and get objects
 * Tigris speaks the S3 API. Bind {@link PutObject} / {@link GetObject}
 * (and the other S3 object ops) in Service init. Alchemy injects the
 * Tigris endpoint and credentials; you never read `AWS_*` yourself.
 *
 * **Example:** Put an object from a Service
 * ```typescript
 * import * as HttpServerResponse from "effect/http/HttpServerResponse";
 *
 * export default class Api extends Fly.Service<Api>()(
 *   "Api",
 *   { app: Site, main: import.meta.url, port: 3000 },
 *   Effect.gen(function* () {
 *     const putObject = yield* Fly.PutObject(Data);
 *     const getObject = yield* Fly.GetObject(Data);
 *
 *     return {
 *       fetch: Effect.gen(function* () {
 *         yield* putObject({
 *           Key: "hello.txt",
 *           Body: "hello",
 *           ContentType: "text/plain",
 *         });
 *         const obj = yield* getObject({ Key: "hello.txt" });
 *         return HttpServerResponse.json({ ok: obj.ETag !== undefined });
 *       }),
 *     };
 *   }).pipe(Effect.provide([Fly.PutObjectHttp, Fly.GetObjectHttp])),
 * ) {}
 * ```
 *
 * ### Fly.Secret
 * You can also set each key yourself with {@link Secret}.
 *
 * **Example:** Manual secrets
 * ```typescript
 * yield* Fly.Secret("BucketName", {
 *   app: Site,
 *   name: "BUCKET_NAME",
 *   value: Data.bucketName,
 * });
 * ```
 *
 * @resource
 * @product Bucket
 */
export const Bucket = Resource<Bucket>("Fly.Bucket");

export class BucketNotCreated extends Data.TaggedError("Fly.BucketNotCreated")<{
  resourceName: string;
}> {}

export class BucketOrgMissing extends Data.TaggedError("Fly.BucketOrgMissing")<{
  orgSlug: string;
}> {}

export class BucketProvisionFailed extends Data.TaggedError("Fly.BucketProvisionFailed")<{
  resourceName: string;
  status: string | undefined;
  errorMessage: string | undefined;
}> {}

class BucketPending extends Data.TaggedError("Fly.BucketPending")<{
  resourceName: string;
  status: string;
}> {}

const TIGRIS = "tigris" as const;

const backoff = Schedule.min([
  Schedule.exponential(Duration.millis(500), 1.5),
  Schedule.spaced(Duration.seconds(5)),
]);

const sanitizeFlyBucketName = (name: string): string => {
  const lowered = name
    .toLowerCase()
    .replace(/[^a-z0-9-]+/g, "-")
    .replace(/-+/g, "-")
    .replace(/^-+|-+$/g, "");
  const clipped = lowered.length > 63 ? lowered.slice(0, 63).replace(/-+$/g, "") : lowered;
  const raw = clipped.length === 0 ? "f" : clipped;
  return /^[a-z]/.test(raw) ? raw : `f${raw}`.slice(0, 63);
};

const resolveBucketName = (id: string, name: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    if (name !== undefined) return sanitizeFlyBucketName(name);
    if (existing !== undefined) return existing;
    return yield* createFlyAppName(id);
  });

const asRecord = (value: unknown): Record<string, unknown> => {
  if (Redacted.isRedacted(value)) {
    return value.pipe(Redacted.value, asRecord);
  }
  if (typeof value === "string") {
    try {
      return asRecord(JSON.parse(value));
    } catch {
      return {};
    }
  }
  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
    return value as Record<string, unknown>;
  }
  return {};
};

const asString = (value: unknown): string | undefined => {
  if (typeof value === "string") {
    return value.length > 0 ? value : undefined;
  }
  if (Redacted.isRedacted(value)) {
    return value.pipe(Redacted.value, asString);
  }
  return undefined;
};

const redact = (value: string | undefined): Redacted.Redacted<string> | undefined =>
  value !== undefined && value.length > 0 ? Redacted.make(value) : undefined;

const keepSecret = (
  next: Redacted.Redacted<string> | undefined,
  previous: Redacted.Redacted<string> | undefined,
): Redacted.Redacted<string> | undefined => next ?? previous;

const envString = (env: Record<string, unknown>, key: BucketSecretName): string | undefined =>
  asString(env[key]);

type ObservedAddOn = Pick<
  AddOnsResponseEdgesItemNode,
  | "id"
  | "name"
  | "status"
  | "errorMessage"
  | "environment"
  | "options"
  | "metadata"
  | "ssoLink"
  | "createdAt"
> & {
  organization?: { slug?: string | null; rawSlug?: string } | null;
};

const unwrapSecret = (value: Redacted.Redacted<string> | string): string =>
  Redacted.isRedacted(value) ? Redacted.value(value) : value;

const desiredOptions = (props: BucketProps): Record<string, unknown> => {
  const options: Record<string, unknown> = {
    public: props.public ?? false,
    accelerate: props.accelerate ?? false,
    website: { domain_name: props.domainName ?? "" },
  };
  if (props.shadowBucket !== undefined) {
    options.shadow_bucket = {
      access_key: props.shadowBucket.accessKey,
      secret_key: unwrapSecret(props.shadowBucket.secretKey),
      region: props.shadowBucket.region,
      name: props.shadowBucket.name,
      endpoint: props.shadowBucket.endpoint,
      write_through: props.shadowBucket.writeThrough ?? false,
    };
  }
  return options;
};

const websiteDomain = (options: Record<string, unknown>): string | undefined => {
  const website = asRecord(options.website);
  return asString(website.domain_name);
};

const toAttrs = (
  addOn: ObservedAddOn,
  previous?: Bucket["Attributes"],
  fallback?: { name?: string; orgSlug?: string },
): Bucket["Attributes"] => {
  const options = asRecord(addOn.options);
  const env = asRecord(addOn.environment);
  const name = addOn.name ?? fallback?.name ?? previous?.name ?? "";
  const orgSlug =
    asString(addOn.organization?.slug) ??
    asString(addOn.organization?.rawSlug) ??
    fallback?.orgSlug ??
    previous?.orgSlug;
  return {
    addOnId: addOn.id,
    name,
    status: addOn.status ?? undefined,
    orgSlug,
    public: typeof options.public === "boolean" ? options.public : (previous?.public ?? false),
    domainName: websiteDomain(options),
    accelerate: options.accelerate === true,
    ssoLink: addOn.ssoLink ?? undefined,
    createdAt: addOn.createdAt,
    accessKeyId: keepSecret(redact(envString(env, "AWS_ACCESS_KEY_ID")), previous?.accessKeyId),
    secretAccessKey: keepSecret(
      redact(envString(env, "AWS_SECRET_ACCESS_KEY")),
      previous?.secretAccessKey,
    ),
    endpoint: keepSecret(redact(envString(env, "AWS_ENDPOINT_URL_S3")), previous?.endpoint),
    region: keepSecret(redact(envString(env, "AWS_REGION")), previous?.region),
    bucketName: keepSecret(redact(envString(env, "BUCKET_NAME") ?? name), previous?.bucketName),
  };
};

const stringRecordOf = (value: unknown): Record<string, string> =>
  Object.fromEntries(
    Object.entries(asRecord(value)).flatMap(([key, item]) => {
      const text = asString(item);
      return text !== undefined ? [[key, text]] : [];
    }),
  );

const hasAlchemyMetadata = (metadata: unknown): boolean => {
  const tags = stringRecordOf(metadata);
  const stack = tags["alchemy::stack"] ?? tags["alchemy.stack"];
  return stack !== undefined && stack.length > 0;
};

const isOwnedAddOn = (addOn: ObservedAddOn): boolean =>
  matchesAlchemyPhysicalName(addOn.name ?? undefined) || hasAlchemyMetadata(addOn.metadata);

export const listTigrisAddOns = Effect.fn(function* () {
  const rows: AddOnsResponseEdgesItemNode[] = [];
  let after: string | undefined;
  for (let i = 0; i < 8; i++) {
    const page = yield* addons.addOns({
      type: TIGRIS,
      first: 50,
      after,
    });
    for (const edge of page.edges ?? []) {
      if (edge?.node != null) rows.push(edge.node);
    }
    if (!page.pageInfo.hasNextPage) break;
    after = page.pageInfo.endCursor ?? undefined;
    if (after === undefined || after.length === 0) break;
  }
  return rows;
});

const findById = (addOnId: string) =>
  listTigrisAddOns().pipe(Effect.map((addOns) => addOns.find((addOn) => addOn.id === addOnId)));

const findByName = (name: string) =>
  listTigrisAddOns().pipe(Effect.map((addOns) => addOns.find((addOn) => addOn.name === name)));

const failedStatus = (status: string | undefined) => status === "error" || status === "failed";

const pendingStatus = (status: string | undefined) =>
  status === "creating" ||
  status === "provisioning" ||
  status === "pending" ||
  status === "pending_create";

const waitUntilReady = (name: string, addOnId: string) =>
  findById(addOnId).pipe(
    Effect.flatMap(
      (
        addOn,
      ): Effect.Effect<AddOnsResponseEdgesItemNode, BucketPending | BucketProvisionFailed> => {
        if (addOn === undefined) {
          return Effect.fail(new BucketPending({ resourceName: name, status: "missing" }));
        }
        const status = addOn.status ?? undefined;
        if (failedStatus(status)) {
          return Effect.fail(
            new BucketProvisionFailed({
              resourceName: name,
              status,
              errorMessage: addOn.errorMessage ?? undefined,
            }),
          );
        }
        if (pendingStatus(status)) {
          return Effect.fail(
            new BucketPending({ resourceName: name, status: status ?? "creating" }),
          );
        }
        return Effect.succeed(addOn);
      },
    ),
    Effect.retry({
      while: (e) => e._tag === "Fly.BucketPending",
      times: 8,
      schedule: backoff,
    }),
    Effect.catchTag("Fly.BucketPending", () => findById(addOnId)),
  );

const waitUntilGone = (addOnId: string, name: string) =>
  Effect.gen(function* () {
    // Best-effort: Tigris often answers "The specified bucket does not
    // exist" (untyped UnknownFlyIoError) for a delete that already
    // succeeded. Never fail the wait on that — only on the add-on still
    // showing up in list.
    yield* Effect.result(
      addons.deleteAddOn({
        input: addOnId.length > 0 ? { addOnId } : { name, provider: TIGRIS },
      }),
    );
    const still =
      (yield* findById(addOnId)) ?? (name.length > 0 ? yield* findByName(name) : undefined);
    if (still !== undefined) {
      return yield* new BucketPending({
        resourceName: name,
        status: still.status ?? "deleting",
      });
    }
  }).pipe(
    Effect.retry({
      while: (e) => e._tag === "Fly.BucketPending",
      schedule: Schedule.spaced("2 seconds"),
      times: 20,
    }),
  );

const resolveOrganization = (orgSlug: string) =>
  addons
    .organization({ slug: orgSlug })
    .pipe(Effect.catchTag("FlyIoParseError", () => Effect.undefined));

const ensureTos = (orgSlug: string, organizationId: string) =>
  Effect.gen(function* () {
    const agreed = yield* addons.agreedToProviderTos({
      slug: orgSlug,
      providerName: TIGRIS,
    });
    if (agreed === true) return;
    const tos = yield* Effect.result(
      addons.createExtensionTosAgreement({
        input: {
          addOnProviderName: TIGRIS,
          organizationId,
        },
      }),
    );
    if (Result.isFailure(tos)) return;
  });

const optionsEqual = (
  observed: Record<string, unknown>,
  desired: Record<string, unknown>,
): boolean => {
  const observedPublic = observed.public === true;
  const desiredPublic = desired.public === true;
  const observedAccelerate = observed.accelerate === true;
  const desiredAccelerate = desired.accelerate === true;
  const observedDomain = websiteDomain(observed) ?? "";
  const desiredDomain = websiteDomain(desired) ?? "";
  if (
    observedPublic !== desiredPublic ||
    observedAccelerate !== desiredAccelerate ||
    observedDomain !== desiredDomain
  ) {
    return false;
  }
  if (desired.shadow_bucket !== undefined) {
    return deepEqual(asRecord(observed.shadow_bucket), desired.shadow_bucket);
  }
  return true;
};

export const BucketProvider = () =>
  Provider.succeed(Bucket, {
    stables: ["addOnId", "name", "orgSlug"],

    diff: Effect.fn(function* ({ news, output }) {
      if (news === undefined || !isResolved(news)) return undefined;
      if (output === undefined) return undefined;
      const desiredName = news.name !== undefined ? sanitizeFlyBucketName(news.name) : output.name;
      const nameChanged = desiredName !== output.name;
      const orgChanged = news.orgSlug !== undefined && news.orgSlug !== output.orgSlug;
      if (nameChanged || orgChanged) {
        return { action: "replace" as const };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const name = yield* resolveBucketName(id, olds?.name, output?.name);
      const found =
        (output?.addOnId !== undefined && output.addOnId.length > 0
          ? yield* findById(output.addOnId)
          : undefined) ?? (yield* findByName(name));
      if (found === undefined) return undefined;
      const attrs = toAttrs(found, output, {
        name,
        orgSlug: output?.orgSlug ?? olds?.orgSlug,
      });
      if (output !== undefined) return attrs;
      return isOwnedAddOn(found) ? attrs : Unowned(attrs);
    }),

    list: Effect.fn(function* () {
      const addOns = yield* listTigrisAddOns();
      return addOns.flatMap((addOn) => (isOwnedAddOn(addOn) ? [toAttrs(addOn)] : []));
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const props = news ?? ({} as BucketProps);
      const name = yield* resolveBucketName(id, props.name, output?.name);
      const orgSlug = props.orgSlug ?? output?.orgSlug ?? (yield* resolveOrgSlug());
      let previous = output;

      // Observe by cached id, then the desired name.
      let current: ObservedAddOn | undefined =
        output?.addOnId !== undefined && output.addOnId.length > 0
          ? yield* findById(output.addOnId)
          : undefined;
      if (current === undefined) {
        current = yield* findByName(name);
      }

      const org = yield* resolveOrganization(orgSlug);
      if (org === undefined) {
        return yield* new BucketOrgMissing({ orgSlug });
      }

      if (current === undefined) {
        yield* ensureTos(orgSlug, org.id);
        const created = yield* Effect.result(
          addons.createAddOn({
            input: {
              type: TIGRIS,
              name,
              organizationId: org.id,
              options: desiredOptions(props),
            },
          }),
        );
        if (Result.isSuccess(created)) {
          current = created.success.addOn;
        } else {
          current = yield* findByName(name);
          if (current === undefined) {
            return yield* created.failure;
          }
        }
        const createdSecrets = current;
        if (current.id.length > 0) {
          current = (yield* waitUntilReady(name, current.id)) ?? current;
        }
        // List/get omit `environment` after create. Keep the create
        // payload as the secrets source for keepSecret below.
        previous = toAttrs(createdSecrets, previous, { name, orgSlug });
      }

      if (current === undefined || current.id.length === 0) {
        return yield* new BucketNotCreated({ resourceName: name });
      }

      const status = current.status ?? undefined;
      if (failedStatus(status)) {
        return yield* new BucketProvisionFailed({
          resourceName: name,
          status,
          errorMessage: current.errorMessage ?? undefined,
        });
      }

      const observedOptions = asRecord(current.options);
      const desired = desiredOptions(props);
      const internal = yield* createInternalTags(id);
      const observedMeta = stringRecordOf(current.metadata);
      const nextMeta = { ...observedMeta, ...internal };
      const optionsChanged = !optionsEqual(observedOptions, desired);
      const metaChanged = !deepEqual(observedMeta, nextMeta);
      if (optionsChanged || metaChanged) {
        const nextOptions = {
          ...observedOptions,
          ...desired,
        };
        const updated = yield* Effect.result(
          addons.updateAddOn({
            input: {
              addOnId: current.id,
              options: optionsChanged ? nextOptions : undefined,
              metadata: metaChanged ? nextMeta : undefined,
            },
          }),
        );
        if (Result.isSuccess(updated)) {
          current = {
            ...current,
            ...updated.success.addOn,
          };
        } else {
          current = (yield* findById(current.id)) ?? current;
        }
      }

      const latest = (yield* findById(current.id)) ?? current;
      // GraphQL list/get omit `environment` after create. Keep credentials
      // from the create payload (or last persisted attrs) via keepSecret.
      const attrs = toAttrs(latest, toAttrs(current, previous, { name, orgSlug }), {
        name,
        orgSlug,
      });
      const observedPublic = asRecord(latest.options).public;
      return {
        ...attrs,
        public:
          typeof observedPublic === "boolean" ? observedPublic : (props.public ?? attrs.public),
        domainName: websiteDomain(asRecord(latest.options)) ?? props.domainName ?? attrs.domainName,
        accelerate:
          typeof asRecord(latest.options).accelerate === "boolean"
            ? (asRecord(latest.options).accelerate as boolean)
            : (props.accelerate ?? attrs.accelerate),
      };
    }),

    delete: Effect.fn(function* ({ output }) {
      const addOnId = output.addOnId;
      const name = output.name;
      if (addOnId.length === 0 && name.length === 0) return;
      // Always wait for the add-on to leave the list. A failed
      // deleteAddOn plus a single list miss is not gone — Tigris
      // list lags, and a bucket still attached to an App is a
      // transient error. waitUntilGone retries delete and only
      // succeeds once list (id and name) is empty.
      yield* waitUntilGone(addOnId, name);
    }),
  });

class BucketSecretVersionMissing extends Data.TaggedError("Fly.BucketSecretVersionMissing")<{
  appName: string;
}> {}

const bucketSecretVersion = (
  appName: string,
  response: machines.AppSecretsUpdateResp | machines.SetAppSecretResponse,
) => {
  const version = response.version ?? response.Version;
  return version !== undefined && Number.isSafeInteger(version) && version >= 0
    ? Effect.succeed(version)
    : Effect.fail(new BucketSecretVersionMissing({ appName }));
};

const requireBucketSecrets = Effect.fn(function* (appName: string, values: Record<string, string>) {
  const required = [
    "BUCKET_NAME",
    "AWS_ACCESS_KEY_ID",
    "AWS_SECRET_ACCESS_KEY",
    "AWS_ENDPOINT_URL_S3",
  ];
  if (required.some((key) => !values[key]?.trim())) {
    return yield* new TigrisCredentialsMissing({
      resourceName: values.BUCKET_NAME || appName,
    });
  }
});

const putSecretValues = (appName: string, values: Record<string, string>) =>
  Effect.gen(function* () {
    yield* requireBucketSecrets(appName, values);
    return yield* machines
      .updateSecrets({
        app_name: appName,
        values,
      })
      .pipe(
        Effect.flatMap((response) => bucketSecretVersion(appName, response)),
        Effect.catchTag("NotFound", () =>
          Effect.gen(function* () {
            const versions: number[] = [];
            for (const [secretName, value] of Object.entries(values)) {
              const version = yield* machines
                .createSecret({
                  app_name: appName,
                  secret_name: secretName,
                  value,
                })
                .pipe(
                  Effect.flatMap((response) => bucketSecretVersion(appName, response)),
                  Effect.catchTag("Conflict", () =>
                    machines
                      .updateSecrets({
                        app_name: appName,
                        values: { [secretName]: value },
                      })
                      .pipe(Effect.flatMap((response) => bucketSecretVersion(appName, response))),
                  ),
                );
              versions.push(version);
            }
            return Math.max(...versions);
          }),
        ),
      );
  });

const envValuesOf = (addOn: ObservedAddOn): Record<string, string> => {
  const env = asRecord(addOn.environment);
  const values: Record<string, string> = {};
  for (const key of BUCKET_SECRET_NAMES) {
    const value = envString(env, key);
    if (value !== undefined) values[key] = value;
  }
  if (values.BUCKET_NAME === undefined && addOn.name != null) {
    values.BUCKET_NAME = addOn.name;
  }
  if (values.AWS_ENDPOINT_URL === undefined && values.AWS_ENDPOINT_URL_S3 !== undefined) {
    values.AWS_ENDPOINT_URL = values.AWS_ENDPOINT_URL_S3;
  }
  return values;
};

const findAttachedBucket = (input: { id?: string; name: string }) =>
  Effect.gen(function* () {
    const listed =
      input.id !== undefined && input.id.length > 0
        ? ((yield* findById(input.id)) ??
          (input.name.length > 0 ? yield* findByName(input.name) : undefined))
        : input.name.length > 0
          ? yield* findByName(input.name)
          : undefined;
    if (listed === undefined) {
      return yield* new BucketPending({
        resourceName: input.name || input.id || "",
        status: "missing",
      });
    }
    const detail = yield* addons
      .addOn({
        id: listed.id,
        name: listed.name ?? input.name,
        provider: TIGRIS,
      })
      .pipe(Effect.catchTag("FlyIoParseError", () => Effect.undefined));
    return detail ?? listed;
  });

const secretsFromBoundEnv = (env: Record<string, string>): Record<string, string> => {
  const values: Record<string, string> = {};
  for (const key of BUCKET_SECRET_NAMES) {
    const value = env[key];
    if (value !== undefined && value.length > 0) values[key] = value;
  }
  if (values.AWS_ENDPOINT_URL === undefined && values.AWS_ENDPOINT_URL_S3 !== undefined) {
    values.AWS_ENDPOINT_URL = values.AWS_ENDPOINT_URL_S3;
  }
  return values;
};

/**
 * Write Tigris `AWS_*` / `BUCKET_NAME` secrets onto an App. Called from
 * {@link Service} reconcile so the secrets exist before Machines boot.
 *
 * Looks up the add-on by id/name (retrying while Tigris is still
 * provisioning) and also copies any already-evaluated `AWS_*` /
 * `BUCKET_NAME` values from binding env — GraphQL `environment` is often
 * empty after create. A missing add-on may use bound values only when the
 * bucket name, credential pair, and S3 endpoint are complete. Partial values
 * are never written. Region is optional, as in the Tigris bindings.
 * Without an attachment, only an explicit `BUCKET_NAME` requests this mode;
 * ordinary AWS region or credential settings do not imply a Bucket.
 * Returns the highest accepted secret-version floor, or `undefined` when
 * no Bucket was requested; this is not a vault snapshot.
 */
export const attachBucketSecrets = Effect.fn(function* (
  appName: string,
  attached: readonly {
    name: string;
    id?: string;
    /** Credentials from the bound Bucket's attributes. */
    values?: Record<string, string>;
  }[],
  boundEnv: Record<string, string> = {},
) {
  if (appName.length === 0) return undefined;
  if (attached.length === 0 && boundEnv.BUCKET_NAME === undefined) {
    return undefined;
  }
  const fromEnv = secretsFromBoundEnv(boundEnv);
  if (attached.length === 0) {
    return yield* putSecretValues(appName, fromEnv);
  }
  const versions: number[] = [];
  for (const item of attached) {
    const name = item.name;
    const id = item.id;
    const fallbackValues: Record<string, string> = {
      ...fromEnv,
      ...item.values,
    };
    if (
      fallbackValues.AWS_ENDPOINT_URL === undefined &&
      fallbackValues.AWS_ENDPOINT_URL_S3 !== undefined
    ) {
      fallbackValues.AWS_ENDPOINT_URL = fallbackValues.AWS_ENDPOINT_URL_S3;
    }
    if (fallbackValues.BUCKET_NAME === undefined && name.length > 0) {
      fallbackValues.BUCKET_NAME = name;
    }
    const row = yield* findAttachedBucket({ id, name }).pipe(
      Effect.retry({
        while: (error) => error._tag === "Fly.BucketPending",
        times: 8,
        schedule: backoff,
      }),
      Effect.catchTag("Fly.BucketPending", () =>
        requireBucketSecrets(appName, fallbackValues).pipe(Effect.as(undefined)),
      ),
    );
    const values = {
      ...fallbackValues,
      ...(row === undefined ? {} : envValuesOf(row)),
    };
    versions.push(yield* putSecretValues(appName, values));
  }
  return versions.length > 0 ? Math.max(...versions) : undefined;
});