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

import * as Binding from "alchemy/Binding";
import type { Resource } from "alchemy/Resource";
import { makeFetchRpcStub, RPC_PATH_PREFIX, type Rpc } from "alchemy/Rpc";
import { CurrentRuntimeContext, type RuntimeContext, sanitizeKey } from "alchemy/RuntimeContext";
import { isYieldableEffectLike } from "alchemy/Util/effect";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as HttpClient from "effect/http/HttpClient";
import type * as HttpClientError from "effect/http/HttpClientError";
import * as HttpClientRequest from "effect/http/HttpClientRequest";
import type * as HttpClientResponse from "effect/http/HttpClientResponse";
import * as Redacted from "effect/Redacted";
import type { BoundTarget, ServiceBinding } from "./MountVolume.ts";
import { RPC_TOKEN_HEADER } from "./rpc.ts";
import type { Service } from "./Service.ts";

/** The deployed caller has no address for the bound Service. */
export class BoundServiceUnavailable extends Data.TaggedError("Fly.BoundServiceUnavailable")<{
  service: string;
}> {
  get message() {
    return `No private address for Fly Service ${this.service}. It publishes no ports, or the caller was deployed before the binding existed.`;
  }
}

/**
 * Client for a Service bound with {@link bindService}: its RPC methods,
 * plus `fetch` for its HTTP routes.
 */
export type ServiceClient<Shape> = Omit<Shape, "fetch" | "run"> & {
  /**
   * Send a request to the Service's `fetch` handler over Fly's private
   * network. A relative URL such as `/users/u1` resolves against the
   * Service's private address.
   */
  fetch(
    request: HttpClientRequest.HttpClientRequest,
  ): Effect.Effect<
    HttpClientResponse.HttpClientResponse,
    HttpClientError.HttpClientError | BoundServiceUnavailable,
    RuntimeContext
  >;
};

/** A published port of a Service bound with {@link bindEndpoint}. */
export interface EndpointClient {
  /** `{appName}.flycast`, the bound Service's private hostname. */
  host: Effect.Effect<string, BoundServiceUnavailable, RuntimeContext>;
  /** The published port. */
  port: number;
  /** `http://{appName}.flycast:{port}`, for a port that serves plain HTTP. */
  url: Effect.Effect<string, BoundServiceUnavailable, RuntimeContext>;
  /** An `HttpClient` whose relative requests go to {@link url}. */
  client: HttpClient.HttpClient.With<HttpClientError.HttpClientError | BoundServiceUnavailable>;
}

type Target<Shape> = Service & Rpc<Shape>;

const isFlyHost = (value: unknown): value is Resource<string, any, any, ServiceBinding> =>
  typeof value === "object" &&
  value !== null &&
  ((value as { Type?: string }).Type === "Fly.Service" ||
    (value as { Type?: string }).Type === "Fly.Machine");

/** Logical id without yielding the Service (the runtime has no engine). */
const logicalIdOf = (target: unknown): string => {
  const id =
    target !== null && (typeof target === "object" || typeof target === "function")
      ? (target as { LogicalId?: unknown }).LogicalId
      : undefined;
  return typeof id === "string" ? id : "";
};

/** Machine env vars the caller's reconcile writes for a bound Service. */
export const boundTargetEnvKeys = (id: string) => ({
  appName: sanitizeKey(`FLY_BIND_${id}_APP`),
  url: sanitizeKey(`FLY_BIND_${id}_URL`),
  token: sanitizeKey(`FLY_BIND_${id}_TOKEN`),
});

/**
 * Record the binding on the caller and transport the target's private
 * address and caller token as Outputs. Returns runtime accessors for them.
 */
const bindTarget = Effect.fn(function* <Shape, Req>(
  target: Target<Shape> | Effect.Effect<Target<Shape>, never, Req>,
  port: number | undefined,
) {
  const id = logicalIdOf(target);
  const keys = boundTargetEnvKeys(id);
  const ctx = yield* CurrentRuntimeContext;
  if (!globalThis.__ALCHEMY_RUNTIME__) {
    // Yielding registers the target and makes the caller depend on it.
    const service = isYieldableEffectLike(target)
      ? yield* target as Effect.Effect<Target<Shape>, never, Req>
      : target;
    // The binding carries the target's Outputs. Unlike props, binding
    // data may stay unresolved between cycle peers, so two Services can
    // bind each other; the caller's reconcile writes them onto its Machines.
    const host = yield* Binding.Host;
    if (isFlyHost(host)) {
      yield* host.bind`${service}`({
        target: {
          service: id,
          appName: service.appName,
          network: service.network,
          privateUrl: service.privateUrl,
          rpcToken: service.rpcToken,
          port,
          endpoints: service.endpoints,
        } as unknown as BoundTarget,
      });
    }
  }
  // Captured at bind time: the host's runtime context reads the values
  // transported onto the Machine.
  const read = (key: string) => (ctx === undefined ? Effect.undefined : ctx.get<unknown>(key));
  const required = (key: string) =>
    read(key).pipe(
      Effect.flatMap((value) =>
        typeof value === "string" && value.length > 0
          ? Effect.succeed(value)
          : Effect.fail(new BoundServiceUnavailable({ service: id })),
      ),
    );
  return {
    appName: required(keys.appName),
    url: required(keys.url),
    token: read(keys.token).pipe(
      Effect.map((value) =>
        Redacted.isRedacted(value)
          ? String(Redacted.value(value))
          : typeof value === "string"
            ? value
            : "",
      ),
    ),
  };
});

/** Resolve `path` (relative or placeholder-based) against `base`. */
const withBase = (base: string, url: string) => {
  const path = url.replace(/^https?:\/\/[^/]+/, "");
  return `${base.replace(/\/$/, "")}${path.startsWith("/") ? path : `/${path}`}`;
};

/**
 * Bind another {@link Service} and get a typed client for it. The client
 * calls the Service's methods (everything its program returns besides
 * `fetch` and `run`) and forwards `fetch` requests, over Fly's private
 * network.
 *
 * Binding makes the caller deploy after the Service and hands it the
 * Service's private address and caller token. Only callers that bind a
 * Service receive its token, so other Services on the same network cannot
 * call its methods. Every call must also carry Fly's signed `Fly-Src`
 * header from the same organization, so the public internet cannot call
 * them. Calls are plain HTTP inside Fly's WireGuard-encrypted network.
 *
 * ### Call a private Service
 * **Example:** Methods on the target
 * ```typescript
 * export default class Users extends Fly.Service<Users>()(
 *   "Users",
 *   { main: import.meta.url, public: false },
 *   Effect.gen(function* () {
 *     return {
 *       list: () => Effect.succeed(USERS),
 *       get: (id: string) =>
 *         Effect.succeed(USERS.find((user) => user.id === id)),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * **Example:** Bind it and call a method
 * ```typescript
 * export default class Orders extends Fly.Service<Orders>()(
 *   "Orders",
 *   { main: import.meta.url, public: false },
 *   Effect.gen(function* () {
 *     const users = yield* Fly.bindService(Users);
 *     return {
 *       list: () =>
 *         Effect.forEach(ORDERS, (order) =>
 *           users
 *             .get(order.userId)
 *             .pipe(Effect.map((user) => ({ ...order, user }))),
 *         ),
 *     };
 *   }),
 * ) {}
 * ```
 *
 * ### Stream and forward HTTP
 * **Example:** A method that returns a Stream
 * ```typescript
 * const all = yield* users.streamAll().pipe(Stream.runCollect);
 * ```
 *
 * **Example:** Send a request to the Service's `fetch`
 * ```typescript
 * const response = yield* users.fetch(HttpClientRequest.get("/users/u1"));
 * ```
 *
 * ### Bind one port
 * {@link bindEndpoint} targets one published port, such as an admin API
 * or a raw TCP protocol. Deploy fails with `Fly.EndpointNotPublished`
 * when the Service does not publish it.
 *
 * **Example:** An admin API on port 9000
 * ```typescript
 * const admin = yield* Fly.bindEndpoint(Users, { port: 9000 });
 * const stats = yield* admin.client.get("/stats");
 * const host = yield* admin.host; // "{appName}.flycast"
 * ```
 *
 * ### Two Services that bind each other
 * Declare each as a tag class with its method shape, and implement each
 * in its own file as the default export of `.make`.
 *
 * **Example:** Ping and Pong
 * ```typescript
 * // src/services.ts
 * export class Ping extends Fly.Service<Ping, Named>()("Ping") {}
 * export class Pong extends Fly.Service<Pong, Named>()("Pong") {}
 *
 * // src/ping.ts
 * export default Ping.make(
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const pong = yield* Fly.bindService(Pong);
 *     return { name: () => Effect.succeed("ping") };
 *   }),
 * );
 * ```
 *
 * ### Errors
 * Each fails the caller's deploy before the caller is created:
 * `Fly.ServiceUnreachable` when the caller and the Service are on
 * different networks, `Fly.ServiceNotBindable` when the Service publishes
 * no ports, and `Fly.EndpointNotPublished` for a port it does not publish.
 *
 * @binding
 * @product Service
 */
export const bindService = <Shape, Req = never>(
  target: Target<Shape> | Effect.Effect<Target<Shape>, never, Req>,
): Effect.Effect<ServiceClient<Shape>, never, Req | HttpClient.HttpClient> =>
  Effect.gen(function* () {
    const http = yield* HttpClient.HttpClient;
    const bound = yield* bindTarget(target, undefined);
    const send = (request: HttpClientRequest.HttpClientRequest, isRpc: boolean) =>
      Effect.gen(function* () {
        const base = yield* bound.url;
        let next = HttpClientRequest.setUrl(request, withBase(base, request.url));
        if (isRpc) {
          next = HttpClientRequest.setHeader(next, RPC_TOKEN_HEADER, yield* bound.token);
        }
        return yield* http.execute(next);
      });
    return makeFetchRpcStub<ServiceClient<Shape>>({
      fetch: (request) =>
        send(request, request.url.includes(RPC_PATH_PREFIX)) as Effect.Effect<
          HttpClientResponse.HttpClientResponse,
          unknown
        >,
      base: {
        fetch: (request: HttpClientRequest.HttpClientRequest) => send(request, false),
      },
    });
  });

/**
 * Bind one published port of another {@link Service}: an admin API on
 * its own port, or a raw TCP protocol. Returns the port's private host,
 * its URL when it serves plain HTTP, and an `HttpClient` whose relative
 * requests go there. See {@link bindService}.
 */
export const bindEndpoint = <Shape, Req = never>(
  target: Target<Shape> | Effect.Effect<Target<Shape>, never, Req>,
  options: { port: number },
): Effect.Effect<EndpointClient, never, Req | HttpClient.HttpClient> =>
  Effect.gen(function* () {
    const http = yield* HttpClient.HttpClient;
    const bound = yield* bindTarget(target, options.port);
    const host = bound.appName.pipe(Effect.map((app) => `${app}.flycast`));
    const url = host.pipe(
      Effect.map((name) =>
        options.port === 80 ? `http://${name}` : `http://${name}:${options.port}`,
      ),
    );
    return {
      host,
      port: options.port,
      url,
      client: HttpClient.mapRequestEffect(http, (request) =>
        url.pipe(
          Effect.map((base) => HttpClientRequest.setUrl(request, withBase(base, request.url))),
        ),
      ),
    } satisfies EndpointClient;
  });