sailfork / t3code-github / .repos/ alchemy-effect/ packages/ railway/ src/ TcpProxy.ts

import { Query, type UnwrapPlan } from "@distilled.cloud/core/query";
import { Railway, type TCPProxy } from "@distilled.cloud/railway";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import { waitUntilDeleted, projectServices as fetchProjectServices } from "./GraphQL.ts";
import { matchesAlchemyPhysicalName } from "./Metadata.ts";
import { ownedProjects, projectEnvironmentIds } from "./Project.ts";
import type { Providers } from "./Providers.ts";

const proxyFields = <E>(proxy: Query<TCPProxy, E>) => ({
  id: proxy.id,
  applicationPort: proxy.applicationPort,
  deletedAt: proxy.deletedAt,
  syncStatus: proxy.syncStatus,
  domain: proxy.domain,
  proxyPort: proxy.proxyPort,
  serviceId: proxy.serviceId,
  environmentId: proxy.environmentId,
});
type CloudProxy = UnwrapPlan<ReturnType<typeof proxyFields>>;

const readTcpProxies = Query.fn((environmentId: string, serviceId: string) =>
  Railway.tcpProxies({ environmentId, serviceId }).pipe(Query.map(proxyFields)),
);

const tcpProxyCreate = Query.fn(
  (input: { applicationPort: number; environmentId: string; serviceId: string }) =>
    proxyFields(Railway.tcpProxyCreate({ input })),
);

const tcpProxyDelete = Query.fn((id: string) => Railway.tcpProxyDelete({ id }));

/**
 * A resource-valued prop: the resource itself, or an Effect that produces
 * it (so `yield* Service(...)` and `Service(...)` both type-check).
 */
type Ref<T> = T | Effect.Effect<T, never, Providers>;

/**
 * Service identity a TCP proxy attaches to. Accepts a `Railway.Service`,
 * `Railway.Postgres`, `Railway.Redis`, or a `{ serviceId }` stub.
 */
export type TcpProxyService = { readonly serviceId: string };

/**
 * Environment identity a TCP proxy is created in. Accepts a
 * `Railway.Project` (its primary environment), a `Railway.Environment`, or
 * an `{ environmentId }` stub.
 */
export type TcpProxyEnvironment = { readonly environmentId: string };

export interface TcpProxyProps {
  /**
   * Service to expose. Accepts a `Railway.Service` or `{ serviceId }`.
   * Mutually exclusive with `postgres` / `redis`. Changing it replaces
   * the proxy.
   */
  service?: Ref<TcpProxyService>;
  /**
   * Postgres service to expose. Same identity as `service`. Changing it
   * replaces the proxy.
   */
  postgres?: Ref<TcpProxyService>;
  /**
   * Redis service to expose. Same identity as `service`. Changing it
   * replaces the proxy.
   */
  redis?: Ref<TcpProxyService>;
  /**
   * Environment the proxy is created in. Accepts a `Railway.Project`
   * (primary environment), a `Railway.Environment`, or `{ environmentId }`.
   * Changing it replaces the proxy.
   */
  environment: Ref<TcpProxyEnvironment>;
  /**
   * Internal application port to proxy to (for example `5432` for
   * Postgres, `6379` for Redis). Changing it replaces the proxy.
   */
  applicationPort: number;
}

export type TcpProxy = Resource<
  "Railway.TcpProxy",
  TcpProxyProps,
  {
    /** Railway TCP proxy id. */
    id: string;
    /** Public proxy hostname (`*.proxy.rlwy.net`). */
    domain: string;
    /** Public proxy port. Pair with `domain` to reach the service. */
    proxyPort: number;
    /** Internal application port being proxied. */
    applicationPort: number;
    /** Service the proxy is attached to. */
    serviceId: string;
    /** Environment the proxy lives in. */
    environmentId: string;
    /** Observed Railway sync status (`ACTIVE`, `CREATING`, …). */
    syncStatus: string;
  },
  never,
  Providers
>;

/**
 * A Railway.TcpProxy exposes a service over public TCP. Identity is the
 * Railway proxy id. There is no in-place update — changing `service`,
 * `postgres`, `redis`, `environment`, or `applicationPort` replaces the
 * proxy.
 *
 * Needed so laptop tests and `ConnectPostgres` from outside the private
 * network can reach Postgres/Redis.
 *
 * @see https://docs.railway.com/networking/tcp-proxy
 *
 * ### Postgres
 * Attach a proxy to a Postgres service on `5432`. `domain` and
 * `proxyPort` are the public endpoint (`{domain}:{proxyPort}`).
 *
 * **Example:** Public TCP for Postgres
 * ```typescript
 * const site = yield* Railway.Project("Site");
 * const db = yield* Railway.Postgres("Db", { project: site });
 * const proxy = yield* Railway.TcpProxy("DbProxy", {
 *   postgres: db,
 *   environment: site,
 *   applicationPort: 5432,
 * });
 * ```
 *
 * :::caution[Changing `applicationPort` replaces the proxy]
 * Railway has no TCP-proxy update API. A new proxy is created, then the
 * old one is deleted.
 * :::
 *
 * ### Redis
 * Same shape on `6379`.
 *
 * **Example:** Public TCP for Redis
 * ```typescript
 * const site = yield* Railway.Project("Site");
 * const cache = yield* Railway.Redis("Cache", { project: site });
 * const proxy = yield* Railway.TcpProxy("CacheProxy", {
 *   redis: cache,
 *   environment: site,
 *   applicationPort: 6379,
 * });
 * ```
 *
 * ### Any service
 * Pass a `Railway.Service` or a `{ serviceId }` stub.
 *
 * **Example:** Stub service id
 * ```typescript
 * const site = yield* Railway.Project("Site");
 * const proxy = yield* Railway.TcpProxy("ApiProxy", {
 *   service: { serviceId: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" },
 *   environment: site,
 *   applicationPort: 8080,
 * });
 * ```
 *
 * :::caution[Changing `service` or `environment` replaces the proxy]
 * The proxy is created on the new service/environment. The old proxy is
 * deleted.
 * :::
 *
 * ### Module-scope declarations
 * Resource-valued props accept the resource or an Effect producing it.
 *
 * **Example:** Module-scope Project and proxy
 * ```typescript
 * // src/db.ts
 * import * as Railway from "@alchemy.run/railway";
 *
 * export const Site = Railway.Project("Site");
 * export const Db = Railway.Postgres("Db", { project: Site });
 * export const DbProxy = Railway.TcpProxy("DbProxy", {
 *   postgres: Db,
 *   environment: Site,
 *   applicationPort: 5432,
 * });
 * ```
 *
 * @resource
 * @product Networking
 */
export const TcpProxy = Resource<TcpProxy>("Railway.TcpProxy");

export class TcpProxyNotCreated extends Data.TaggedError("Railway.TcpProxyNotCreated")<{
  serviceId: string;
  environmentId: string;
  applicationPort: number;
}> {}

export class TcpProxyTargetMissing extends Data.TaggedError("Railway.TcpProxyTargetMissing")<{
  message: string;
}> {}

const isGone = (proxy: CloudProxy | undefined) =>
  proxy === undefined || proxy.deletedAt != null || proxy.syncStatus === "DELETED";

const normalizeDomain = (domain: string) => domain.replace(/\.+$/, "");

const toAttrs = (proxy: CloudProxy): TcpProxy["Attributes"] => ({
  id: proxy.id,
  domain: normalizeDomain(proxy.domain),
  proxyPort: proxy.proxyPort,
  applicationPort: proxy.applicationPort,
  serviceId: proxy.serviceId,
  environmentId: proxy.environmentId,
  syncStatus: proxy.syncStatus,
});

const serviceIdOf = (value: unknown): string | undefined => {
  if (value === null || typeof value !== "object") return undefined;
  const rec = value as { serviceId?: unknown };
  if (typeof rec.serviceId === "string" && rec.serviceId.length > 0) {
    return rec.serviceId;
  }
  return undefined;
};

const environmentIdOf = (value: unknown): string | undefined => {
  if (value === null || typeof value !== "object") return undefined;
  const rec = value as { environmentId?: unknown };
  if (typeof rec.environmentId === "string" && rec.environmentId.length > 0) {
    return rec.environmentId;
  }
  return undefined;
};

const targetOf = (props: Pick<TcpProxyProps, "service" | "postgres" | "redis">) =>
  props.service ?? props.postgres ?? props.redis;

const listProxies = (environmentId: string, serviceId: string) =>
  readTcpProxies(environmentId, serviceId).pipe(
    Effect.map((items) => items.filter((proxy) => !isGone(proxy))),
    Effect.catchTag("RailwayNotFound", () => Effect.succeed([] as ReadonlyArray<CloudProxy>)),
  );

const findById = (environmentId: string, serviceId: string, id: string) =>
  listProxies(environmentId, serviceId).pipe(
    Effect.map((items) => items.find((proxy) => proxy.id === id)),
  );

const findByPort = (environmentId: string, serviceId: string, applicationPort: number) =>
  listProxies(environmentId, serviceId).pipe(
    Effect.map((items) => items.find((proxy) => proxy.applicationPort === applicationPort)),
  );

const observe = Effect.fn(function* (input: {
  environmentId: string;
  serviceId: string;
  applicationPort?: number;
  id?: string;
}) {
  if (input.id !== undefined && input.id.length > 0) {
    const byId = yield* findById(input.environmentId, input.serviceId, input.id);
    if (byId !== undefined) return byId;
  }
  if (input.applicationPort !== undefined) {
    return yield* findByPort(input.environmentId, input.serviceId, input.applicationPort);
  }
  return undefined;
});

const waitUntilGone = (environmentId: string, serviceId: string, id: string) =>
  waitUntilDeleted(
    "TcpProxy",
    id,
    findById(environmentId, serviceId, id).pipe(Effect.map((proxy) => proxy === undefined)),
  );

export const TcpProxyProvider = () =>
  Provider.succeed(TcpProxy, {
    stables: ["id", "domain", "proxyPort", "serviceId", "environmentId"],
    nuke: { dependsOn: ["Railway.Project"] },

    list: Effect.fn(function* () {
      const projects = yield* ownedProjects();
      const rows = yield* Effect.forEach(projects, (project) =>
        Effect.gen(function* () {
          const live = yield* fetchProjectServices(project.projectId, (service) => ({
            id: service.id,
            name: service.name,
            deletedAt: service.deletedAt,
          })).pipe(Effect.catchTag("RailwayNotFound", () => Effect.undefined));
          const services = (live ?? []).filter(
            (service) => service.deletedAt == null && matchesAlchemyPhysicalName(service.name),
          );
          const envIds = yield* projectEnvironmentIds(project);
          const nested = yield* Effect.forEach(services, (service) =>
            Effect.forEach(envIds, (environmentId) =>
              listProxies(environmentId, service.id).pipe(
                Effect.map((proxies) => proxies.map((proxy) => toAttrs(proxy))),
              ),
            ).pipe(Effect.map((rows) => rows.flat())),
          );
          return nested.flat();
        }),
      );
      return rows.flat();
    }),

    diff: Effect.fn(function* ({ news, output }) {
      if (news === undefined || !isResolved(news)) return undefined;
      if (output === undefined) return undefined;
      const serviceId = serviceIdOf(targetOf(news));
      const environmentId = environmentIdOf(news.environment);
      const serviceChanged = serviceId !== undefined && serviceId !== output.serviceId;
      const environmentChanged =
        environmentId !== undefined && environmentId !== output.environmentId;
      const portChanged = news.applicationPort !== output.applicationPort;
      if (serviceChanged || environmentChanged || portChanged) {
        return { action: "replace" as const };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ olds, output }) {
      const serviceId = output?.serviceId ?? serviceIdOf(targetOf(olds ?? {}));
      const environmentId = output?.environmentId ?? environmentIdOf(olds?.environment);
      const applicationPort = output?.applicationPort ?? olds?.applicationPort;
      if (serviceId === undefined || environmentId === undefined) {
        return undefined;
      }
      const found = yield* observe({ environmentId, serviceId, applicationPort, id: output?.id });
      if (found === undefined) return undefined;
      return toAttrs(found);
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      const props = news ?? ({} as TcpProxyProps);
      const serviceId = serviceIdOf(targetOf(props)) ?? output?.serviceId;
      const environmentId = environmentIdOf(props.environment) ?? output?.environmentId;
      const applicationPort = props.applicationPort ?? output?.applicationPort;
      if (serviceId === undefined || environmentId === undefined) {
        return yield* new TcpProxyTargetMissing({
          message: "TcpProxy requires a service (or postgres/redis) and an environment",
        });
      }
      if (applicationPort === undefined) {
        return yield* new TcpProxyNotCreated({ serviceId, environmentId, applicationPort: 0 });
      }

      let current = yield* observe({ environmentId, serviceId, applicationPort, id: output?.id });

      if (current === undefined) {
        const created = yield* tcpProxyCreate({ applicationPort, environmentId, serviceId }).pipe(
          Effect.catchTag("RailwayValidationError", () => Effect.undefined),
        );
        current =
          created !== undefined && !isGone(created)
            ? created
            : yield* observe({ environmentId, serviceId, applicationPort });
      }

      if (current === undefined || isGone(current)) {
        return yield* new TcpProxyNotCreated({ serviceId, environmentId, applicationPort });
      }

      return toAttrs(current);
    }),

    delete: Effect.fn(function* ({ output }) {
      const id = output.id;
      if (id.length === 0) return;
      yield* tcpProxyDelete(id).pipe(
        // Railway serializes proxy mutations per environment: a delete
        // racing an in-flight deploy fails with "Cannot delete TCP proxy:
        // an operation is already in progress".
        Effect.retry({
          while: (e) => e._tag === "RailwayOperationInProgress",
          schedule: Schedule.spaced("3 seconds"),
          times: 10,
        }),
        Effect.catchTag("RailwayNotFound", () => Effect.void),
      );
      if (output.environmentId.length > 0 && output.serviceId.length > 0) {
        yield* waitUntilGone(output.environmentId, output.serviceId, id);
      }
    }),
  });