sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Transfer/ Server.ts

import * as transfer from "@distilled.cloud/aws/transfer";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

export class ServerNotReady extends Data.TaggedError("ServerNotReady")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export class ServerUnexpectedResponse extends Data.TaggedError("ServerUnexpectedResponse")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export interface ServerProps {
  /**
   * File-transfer protocols the server exposes.
   * @default ["SFTP"]
   */
  protocols?: transfer.Protocol[];
  /**
   * Storage domain the server serves files from. Changing it replaces the
   * server.
   * @default "S3"
   */
  domain?: transfer.Domain;
  /**
   * Where the server endpoint is hosted. `PUBLIC` is internet-facing;
   * `VPC` places it inside a VPC (requires `endpointDetails`).
   * @default "PUBLIC"
   */
  endpointType?: transfer.EndpointType;
  /**
   * VPC endpoint configuration (subnets, security groups, address
   * allocations). Required when `endpointType` is `VPC`.
   */
  endpointDetails?: transfer.EndpointDetails;
  /**
   * How users authenticate. `SERVICE_MANAGED` stores SSH keys in Transfer
   * Family; `API_GATEWAY`/`AWS_LAMBDA`/`AWS_DIRECTORY_SERVICE` delegate to a
   * custom identity provider. Changing it replaces the server.
   * @default "SERVICE_MANAGED"
   */
  identityProviderType?: transfer.IdentityProviderType;
  /**
   * Configuration for a custom identity provider (required unless
   * `identityProviderType` is `SERVICE_MANAGED`).
   */
  identityProviderDetails?: transfer.IdentityProviderDetails;
  /**
   * IAM role ARN Transfer Family assumes to publish CloudWatch logs.
   */
  loggingRole?: string;
  /**
   * Name of the security policy (cipher/algorithm set) attached to the server.
   */
  securityPolicyName?: string;
  /**
   * Banner shown to clients before authentication (SFTP/FTPS only).
   */
  preAuthenticationLoginBanner?: string;
  /**
   * Banner shown to clients after authentication.
   */
  postAuthenticationLoginBanner?: string;
  /**
   * Protocol-specific settings (passive IP, TLS session resumption, etc.).
   */
  protocolDetails?: transfer.ProtocolDetails;
  /**
   * S3 storage options such as directory-listing optimization.
   */
  s3StorageOptions?: transfer.S3StorageOptions;
  /**
   * Workflows triggered on file upload.
   */
  workflowDetails?: transfer.WorkflowDetails;
  /**
   * CloudWatch Logs log-group ARNs the server streams structured logs to.
   */
  structuredLogDestinations?: string[];
  /**
   * IP address type of the endpoint.
   * @default "IPV4"
   */
  ipAddressType?: transfer.IpAddressType;
  /**
   * User-defined tags for the server.
   */
  tags?: Record<string, string>;
}

export interface Server extends Resource<
  "AWS.Transfer.Server",
  ServerProps,
  {
    /**
     * AWS-assigned server ID (e.g. `s-0123456789abcdef0`). Clients connect to
     * `{serverId}.server.transfer.{region}.amazonaws.com`.
     */
    serverId: string;
    /**
     * ARN of the server.
     */
    arn: string;
    /**
     * Where the server endpoint is hosted (`PUBLIC` or `VPC`).
     */
    endpointType: string;
    /**
     * Storage domain the server serves files from (`S3` or `EFS`).
     */
    domain: string;
    /**
     * How users authenticate.
     */
    identityProviderType: string;
    /**
     * File-transfer protocols the server exposes.
     */
    protocols: string[];
    /**
     * Current lifecycle state (e.g. `ONLINE`, `STARTING`).
     */
    state: string | undefined;
    /**
     * Current tags reported for the server.
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An AWS Transfer Family server — a managed SFTP/FTPS/FTP/AS2 endpoint in
 * front of S3 or EFS storage. A running server is billed hourly (plus data
 * transfer), so create it only when needed and destroy it promptly.
 * ### Creating a Server
 * **Example:** Public SFTP Server (Service-Managed Users)
 * ```typescript
 * const server = yield* Server("Sftp", {
 *   protocols: ["SFTP"],
 *   domain: "S3",
 *   endpointType: "PUBLIC",
 *   identityProviderType: "SERVICE_MANAGED",
 * });
 * ```
 *
 * ### Adding Users
 * **Example:** SFTP Server with a Service-Managed User
 * ```typescript
 * const server = yield* Server("Sftp", {
 *   protocols: ["SFTP"],
 *   identityProviderType: "SERVICE_MANAGED",
 * });
 *
 * // Role Transfer Family assumes to access the S3 storage backend
 * const role = yield* AWS.IAM.Role("TransferUserRole", {
 *   assumeRolePolicyDocument: {
 *     Version: "2012-10-17",
 *     Statement: [
 *       {
 *         Effect: "Allow",
 *         Principal: { Service: "transfer.amazonaws.com" },
 *         Action: ["sts:AssumeRole"],
 *       },
 *     ],
 *   },
 *   inlinePolicies: {
 *     s3: {
 *       Version: "2012-10-17",
 *       Statement: [
 *         {
 *           Effect: "Allow",
 *           Action: ["s3:ListBucket", "s3:GetObject", "s3:PutObject"],
 *           Resource: [bucket.bucketArn, Output.interpolate`${bucket.bucketArn}/*`],
 *         },
 *       ],
 *     },
 *   },
 * });
 *
 * const user = yield* User("Alice", {
 *   serverId: server.serverId,
 *   userName: "alice",
 *   role: role.roleArn,
 *   homeDirectory: Output.interpolate`/${bucket.bucketName}/alice`,
 *   sshPublicKeyBody: "ssh-ed25519 AAAA...",
 * });
 * ```
 *
 * @resource
 */
export const Server = Resource<Server>("AWS.Transfer.Server");

const toTagRecord = (
  tags: Array<{ Key?: string; Value?: string }> | undefined,
): Record<string, string> =>
  Object.fromEntries(
    (tags ?? [])
      .filter(
        (tag): tag is { Key: string; Value: string } =>
          typeof tag.Key === "string" && typeof tag.Value === "string",
      )
      .map((tag) => [tag.Key, tag.Value]),
  );

export const ServerProvider = () =>
  Provider.effect(
    Server,
    Effect.gen(function* () {
      const describe = Effect.fn(function* (serverId: string) {
        const response = yield* transfer
          .describeServer({ ServerId: serverId })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
        return response?.Server;
      });

      const readTags = Effect.fn(function* (arn: string) {
        const response = yield* transfer
          .listTagsForResource({ Arn: arn })
          .pipe(Effect.orElseSucceed(() => undefined));
        return toTagRecord(response?.Tags);
      });

      // Servers transition through STARTING before ONLINE; updateServer and
      // deleteServer require a settled state. Budget ~7 minutes (10s x 42).
      const waitUntilSettled = Effect.fn(function* (serverId: string) {
        const settlePolicy = Schedule.max([Schedule.fixed("10 seconds"), Schedule.recurs(42)]);
        return yield* describe(serverId).pipe(
          Effect.flatMap((server) => {
            if (
              server !== undefined &&
              (server.State === "STARTING" || server.State === "STOPPING")
            ) {
              return Effect.fail(
                new ServerNotReady({
                  message: `Transfer server '${serverId}' still settling (state: ${server.State})`,
                }),
              );
            }
            return Effect.succeed(server);
          }),
          Effect.retry({ schedule: settlePolicy }),
        );
      });

      const toAttrs = Effect.fn(function* (server: transfer.DescribedServer) {
        if (!server.ServerId) {
          return yield* new ServerUnexpectedResponse({
            message: "Transfer server is missing its ServerId",
          });
        }
        return {
          serverId: server.ServerId,
          arn: server.Arn,
          endpointType: server.EndpointType ?? "PUBLIC",
          domain: server.Domain ?? "S3",
          identityProviderType: server.IdentityProviderType ?? "SERVICE_MANAGED",
          protocols: [...(server.Protocols ?? [])],
          state: server.State,
          tags: yield* readTags(server.Arn),
        };
      });

      return {
        stables: ["serverId", "arn"],

        diff: Effect.fn(function* ({ olds, news }) {
          if (!isResolved(news)) return undefined;
          // Domain and identity-provider type are create-only.
          if (
            (news.domain ?? "S3") !== (olds?.domain ?? "S3") ||
            (news.identityProviderType ?? "SERVICE_MANAGED") !==
              (olds?.identityProviderType ?? "SERVICE_MANAGED")
          ) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, output }) {
          // ServerId is AWS-assigned, so a server can only be found via a
          // previously-persisted output (like an auto-id VPC).
          if (!output?.serverId) return undefined;
          const server = yield* describe(output.serverId);
          if (!server?.ServerId) return undefined;
          const attrs = yield* toAttrs(server);
          return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          // 1. Observe — cloud state is authoritative (via the id cache).
          let serverId = output?.serverId;
          let observed = serverId ? yield* describe(serverId) : undefined;

          // 2. Ensure — create if missing.
          if (observed === undefined) {
            const created = yield* transfer.createServer({
              Protocols: news.protocols ?? ["SFTP"],
              Domain: news.domain,
              EndpointType: news.endpointType,
              EndpointDetails: news.endpointDetails,
              IdentityProviderType: news.identityProviderType,
              IdentityProviderDetails: news.identityProviderDetails,
              LoggingRole: news.loggingRole,
              SecurityPolicyName: news.securityPolicyName,
              PreAuthenticationLoginBanner: news.preAuthenticationLoginBanner,
              PostAuthenticationLoginBanner: news.postAuthenticationLoginBanner,
              ProtocolDetails: news.protocolDetails,
              S3StorageOptions: news.s3StorageOptions,
              WorkflowDetails: news.workflowDetails,
              StructuredLogDestinations: news.structuredLogDestinations,
              IpAddressType: news.ipAddressType,
              Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                Key,
                Value,
              })),
            });
            serverId = created.ServerId;
          } else {
            // 3. Sync — push mutable configuration. updateServer requires a
            //    settled server state.
            yield* waitUntilSettled(serverId!);
            yield* transfer.updateServer({
              ServerId: serverId!,
              Protocols: news.protocols,
              EndpointType: news.endpointType,
              EndpointDetails: news.endpointDetails,
              IdentityProviderDetails: news.identityProviderDetails,
              LoggingRole: news.loggingRole,
              SecurityPolicyName: news.securityPolicyName,
              PreAuthenticationLoginBanner: news.preAuthenticationLoginBanner,
              PostAuthenticationLoginBanner: news.postAuthenticationLoginBanner,
              ProtocolDetails: news.protocolDetails,
              S3StorageOptions: news.s3StorageOptions,
              WorkflowDetails: news.workflowDetails,
              StructuredLogDestinations: news.structuredLogDestinations,
              IpAddressType: news.ipAddressType,
            });
          }

          // Wait for the server to settle so downstream User creation and the
          // returned state are stable.
          observed = yield* waitUntilSettled(serverId!);
          if (!observed?.ServerId || !observed.Arn) {
            return yield* new ServerUnexpectedResponse({
              message: `Transfer server '${serverId}' not found after reconcile`,
            });
          }

          // 3b. Sync tags — diff against OBSERVED cloud tags.
          const arn = observed.Arn;
          const observedTags = yield* readTags(arn);
          const { upsert, removed } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* transfer.tagResource({ Arn: arn, Tags: upsert });
          }
          if (removed.length > 0) {
            yield* transfer.untagResource({ Arn: arn, TagKeys: removed });
          }

          yield* session.note(observed.ServerId);
          return yield* toAttrs(observed);
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* transfer
            .deleteServer({ ServerId: output.serverId })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),

        list: () =>
          transfer.listServers.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.Servers ?? []).filter((server) => server.ServerId !== undefined),
              ),
            ),
            Effect.flatMap(
              Effect.forEach(
                (server) =>
                  toAttrs({
                    Arn: server.Arn,
                    ServerId: server.ServerId,
                    Domain: server.Domain,
                    EndpointType: server.EndpointType,
                    IdentityProviderType: server.IdentityProviderType,
                    State: server.State,
                    LoggingRole: server.LoggingRole,
                  }),
                { concurrency: 4 },
              ),
            ),
          ),
      };
    }),
  );