sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ SageMaker/ Endpoint.ts

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

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

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

export type EndpointStatus = sagemaker.EndpointStatus;

export interface EndpointProps {
  /**
   * Name of the endpoint. Maximum 63 characters.
   * @default ${app}-${stage}-${id}
   */
  endpointName?: string;
  /**
   * Name of the `EndpointConfig` that describes the models and hosting
   * resources to deploy. Changing it updates the live endpoint in place
   * (blue/green by default on the SageMaker side).
   */
  endpointConfigName: string;
  /**
   * Deployment (blue/green or rolling) configuration applied when the
   * endpoint is updated to a new configuration.
   */
  deploymentConfig?: sagemaker.DeploymentConfig;
  /**
   * Tags to associate with the endpoint. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface Endpoint extends Resource<
  "AWS.SageMaker.Endpoint",
  EndpointProps,
  {
    /**
     * The endpoint's name.
     */
    endpointName: string;
    /**
     * ARN of the endpoint.
     */
    endpointArn: string;
    /**
     * Lifecycle status of the endpoint after reconcile (`InService`).
     */
    endpointStatus: EndpointStatus | undefined;
  },
  never,
  Providers
> {}

/**
 * An Amazon SageMaker Endpoint — the live, invocable deployment of an
 * `EndpointConfig`. Provisioning takes minutes and **bills while the
 * endpoint exists** (serverless variants bill per request; instance variants
 * bill per instance-hour). Destroy endpoints promptly.
 *
 * Invoke a deployed endpoint from a function with
 * `AWS.SageMakerRuntime.InvokeEndpoint`.
 * ### Creating Endpoints
 * **Example:** Deploy an EndpointConfig
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const endpoint = yield* AWS.SageMaker.Endpoint("MyEndpoint", {
 *   endpointConfigName: config.endpointConfigName,
 * });
 * ```
 *
 * ### Invoking
 * **Example:** Invoke from a Lambda function
 * ```typescript
 * // init
 * const invoke = yield* AWS.SageMakerRuntime.InvokeEndpoint(
 *   endpoint.endpointName,
 * );
 *
 * // runtime
 * const result = yield* invoke({
 *   ContentType: "application/json",
 *   Body: JSON.stringify({ instances: [[1, 2, 3, 4]] }),
 * });
 * ```
 *
 * @resource
 */
export const Endpoint = Resource<Endpoint>("AWS.SageMaker.Endpoint");

const createEndpointName = (id: string, props: { endpointName?: string | undefined }) =>
  props.endpointName
    ? Effect.succeed(props.endpointName)
    : createPhysicalName({ id, maxLength: 63 });

const fetchEndpointTags = Effect.fn(function* (arn: string) {
  const response = yield* sagemaker
    .listTags({ ResourceArn: arn })
    .pipe(Effect.catchTag("AccessDeniedException", () => Effect.undefined));
  return Object.fromEntries(
    (response?.Tags ?? []).flatMap((tag) =>
      tag.Key !== undefined ? [[tag.Key, tag.Value ?? ""]] : [],
    ),
  );
});

const describeEndpointOrUndefined = (name: string) =>
  sagemaker
    .describeEndpoint({ EndpointName: name })
    .pipe(Effect.catchTag("EndpointNotFound", () => Effect.undefined));

/**
 * The endpoint is still transitioning toward the awaited state — retried by
 * the bounded wait schedule.
 */
class EndpointNotReady extends Data.TaggedError("EndpointNotReady")<{
  readonly endpointName: string;
  readonly status: string | undefined;
}> {}

/**
 * The endpoint's asynchronous provisioning converged to the terminal
 * `Failed` status (e.g. the container image could not be pulled or the model
 * server failed its health checks).
 */
export class EndpointProvisioningFailed extends Data.TaggedError("EndpointProvisioningFailed")<{
  readonly endpointName: string;
  readonly message: string | undefined;
}> {}

// Explicitly-typed retry wrapper — an inline `Effect.retry` in provider
// lifecycle code leaks `Retry.Return`'s conditional type into declaration
// emit and widens the provider layer to `unknown` for every consumer of
// `AWS.providers()`.
const retryWhileNotReady = <A, E extends { readonly _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "EndpointNotReady",
    // Endpoint provisioning takes ~3-10 min; poll every 15s up to ~20 min.
    schedule: Schedule.max([Schedule.spaced("15 seconds"), Schedule.recurs(80)]),
  });

const waitForEndpoint = (name: string, target: "InService" | "Gone") =>
  retryWhileNotReady(
    Effect.gen(function* () {
      const described = yield* describeEndpointOrUndefined(name);
      if (target === "Gone") {
        if (described === undefined) return;
        return yield* new EndpointNotReady({
          endpointName: name,
          status: described.EndpointStatus,
        });
      }
      if (described?.EndpointStatus === "InService") return;
      if (described?.EndpointStatus === "Failed") {
        return yield* new EndpointProvisioningFailed({
          endpointName: name,
          message: described.FailureReason,
        });
      }
      return yield* new EndpointNotReady({
        endpointName: name,
        status: described?.EndpointStatus,
      });
    }),
  );

export const EndpointProvider = () =>
  Provider.effect(
    Endpoint,
    Effect.gen(function* () {
      return {
        stables: ["endpointName", "endpointArn"],
        list: () =>
          Effect.gen(function* () {
            const summaries = yield* sagemaker.listEndpoints.pages({}).pipe(
              EffectStream.runCollect,
              Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Endpoints ?? [])),
            );
            return summaries.flatMap((s) =>
              s.EndpointName !== undefined && s.EndpointArn !== undefined
                ? [
                    {
                      endpointName: s.EndpointName,
                      endpointArn: s.EndpointArn,
                      endpointStatus: s.EndpointStatus,
                    },
                  ]
                : [],
            );
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.endpointName ?? (yield* createEndpointName(id, olds ?? {}));
          const described = yield* describeEndpointOrUndefined(name);
          if (!described || described.EndpointStatus === "Deleting") {
            return undefined;
          }
          const attrs = {
            endpointName: described.EndpointName,
            endpointArn: described.EndpointArn,
            endpointStatus: described.EndpointStatus,
          };
          const tags = yield* fetchEndpointTags(described.EndpointArn);
          return (yield* hasAlchemyTags(id, tags as Tags)) ? attrs : Unowned(attrs);
        }),
        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return;
          if (olds === undefined) return;
          const oldName = yield* createEndpointName(id, olds);
          const newName = yield* createEndpointName(id, news);
          if (oldName !== newName) {
            return { action: "replace" } as const;
          }
          // endpointConfigName changes update the live endpoint in place.
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          if (!news) {
            return yield* new SageMakerEndpointInvalidProps({
              message: "SageMaker Endpoint requires props",
            });
          }
          const name = output?.endpointName ?? (yield* createEndpointName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          // Observe.
          let described = yield* describeEndpointOrUndefined(name);

          // A terminally-failed endpoint cannot be updated — delete it and
          // fall through to a fresh create so the reconciler converges.
          if (described?.EndpointStatus === "Failed") {
            yield* session.note(
              `Endpoint ${name} is Failed (${described.FailureReason ?? "unknown"}) — recreating`,
            );
            yield* sagemaker
              .deleteEndpoint({ EndpointName: name })
              .pipe(Effect.catchTag("EndpointNotFound", () => Effect.void));
            yield* waitForEndpoint(name, "Gone");
            described = undefined;
          }

          // Ensure — create if missing; tolerate the already-exists race.
          if (described === undefined) {
            yield* sagemaker
              .createEndpoint({
                EndpointName: name,
                EndpointConfigName: news.endpointConfigName,
                DeploymentConfig: news.deploymentConfig,
                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              })
              .pipe(Effect.catchTag("EndpointAlreadyExists", () => Effect.void));
            yield* session.note(`Creating endpoint ${name}...`);
          } else if (
            described.EndpointConfigName !== news.endpointConfigName &&
            described.EndpointStatus === "InService"
          ) {
            // Sync — roll the live endpoint onto the desired configuration.
            yield* sagemaker.updateEndpoint({
              EndpointName: name,
              EndpointConfigName: news.endpointConfigName,
              DeploymentConfig: news.deploymentConfig,
            });
            yield* session.note(
              `Updating endpoint ${name} to config ${news.endpointConfigName}...`,
            );
          }

          // Converge to InService (also settles Creating/Updating states we
          // observed mid-flight, e.g. after a crashed reconcile).
          yield* waitForEndpoint(name, "InService");
          const final = yield* describeEndpointOrUndefined(name);
          if (final === undefined) {
            return yield* new SageMakerEndpointUnexpectedResponse({
              message: `failed to read reconciled endpoint ${name}`,
            });
          }

          // Sync tags — diff against OBSERVED cloud tags.
          const currentTags = yield* fetchEndpointTags(final.EndpointArn);
          const { removed, upsert } = diffTags(currentTags, desiredTags);
          if (removed.length > 0) {
            yield* sagemaker.deleteTags({
              ResourceArn: final.EndpointArn,
              TagKeys: removed,
            });
          }
          if (upsert.length > 0) {
            yield* sagemaker.addTags({
              ResourceArn: final.EndpointArn,
              Tags: upsert.map(({ Key, Value }) => ({ Key, Value })),
            });
          }

          yield* session.note(final.EndpointArn);
          return {
            endpointName: final.EndpointName,
            endpointArn: final.EndpointArn,
            endpointStatus: final.EndpointStatus,
          };
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* sagemaker
            .deleteEndpoint({ EndpointName: output.endpointName })
            .pipe(Effect.catchTag("EndpointNotFound", () => Effect.void));
          yield* waitForEndpoint(output.endpointName, "Gone");
        }),
      };
    }),
  );