@rc312/effect-aws-imds 0.0.0-stage → 0.2.0

package/src/config.ts

@@ -0,0 +1,96 @@
+import { Config, Context, Duration, Effect, Layer, Schedule } from "effect";
+
+const RETRY_BASE_DELAY = Duration.millis(50);
+
+/**
+ * The default retry policy: jittered exponential backoff from 50 ms, bounded
+ * to `times` retries after the first attempt.
+ *
+ * @since 0.1.0
+ */
+const retryPolicy = (times: number) =>
+  Schedule.exponential(RETRY_BASE_DELAY).pipe(
+    Schedule.jittered,
+    Schedule.upTo({ times })
+  );
+
+/**
+ * Resolved settings read by every IMDS layer.
+ *
+ * @since 0.1.0
+ */
+interface AwsImdsSettings {
+  /** Base URL of the metadata service. */
+  readonly endpoint: string;
+  /**
+   * Requested session token lifetime. The value sent to IMDS is rounded down
+   * to whole seconds and clamped to 1 second through 6 hours.
+   */
+  readonly tokenTtl: Duration.Duration;
+  /** Timeout for each individual HTTP attempt. */
+  readonly attemptTimeout: Duration.Duration;
+  /**
+   * Policy for retrying timeouts, transport errors, and transient statuses.
+   * It is the only bound on retries, so it must stop on its own, for example
+   * with `Schedule.upTo`.
+   */
+  readonly retrySchedule: Schedule.Schedule<unknown>;
+}
+
+/**
+ * Partial settings for `AwsImdsConfig.layer` and `AwsImdsConfig.layerConfig`.
+ * Omitted fields keep their defaults.
+ *
+ * @since 0.1.0
+ */
+interface AwsImdsOptions {
+  /** Defaults to `http://169.254.169.254`; use `http://[fd00:ec2::254]` on IPv6-only instances. */
+  readonly endpoint?: string | undefined;
+  /** Defaults to 6 hours. */
+  readonly tokenTtl?: Duration.Input | undefined;
+  /** Defaults to 1 second. */
+  readonly attemptTimeout?: Duration.Input | undefined;
+  /** Defaults to `retryPolicy(2)`. Must be bounded, for example with `Schedule.upTo`. */
+  readonly retrySchedule?: Schedule.Schedule<unknown> | undefined;
+}
+
+const defaults: AwsImdsSettings = {
+  attemptTimeout: Duration.seconds(1),
+  endpoint: "http://169.254.169.254",
+  retrySchedule: retryPolicy(2),
+  tokenTtl: Duration.hours(6),
+};
+
+const resolve = (options: AwsImdsOptions): AwsImdsSettings => ({
+  attemptTimeout: Duration.fromInputUnsafe(
+    options.attemptTimeout ?? defaults.attemptTimeout
+  ),
+  endpoint: options.endpoint ?? defaults.endpoint,
+  retrySchedule: options.retrySchedule ?? defaults.retrySchedule,
+  tokenTtl: Duration.fromInputUnsafe(options.tokenTtl ?? defaults.tokenTtl),
+});
+
+/**
+ * Settings for the IMDS layers, with defaults when nothing provides them.
+ *
+ * Provide an override to the layers with `Layer.provide`; merging it beside
+ * them has no effect on how they are built.
+ *
+ * @since 0.1.0
+ */
+class AwsImdsConfig extends Context.Reference<AwsImdsSettings>(
+  "@rc312/effect-aws-imds/AwsImdsConfig",
+  { defaultValue: () => defaults }
+) {
+  /** Overrides the given settings and keeps defaults for the rest. */
+  static readonly layer = (options: AwsImdsOptions) =>
+    Layer.sync(AwsImdsConfig, () => resolve(options));
+
+  /** Reads settings from `Config`, field by field or as one `Config`. */
+  static readonly layerConfig = (config: Config.Wrap<AwsImdsOptions>) =>
+    Layer.effect(AwsImdsConfig, Effect.map(Config.unwrap(config), resolve));
+}
+
+export { AwsImdsConfig, retryPolicy };
+
+export type { AwsImdsOptions, AwsImdsSettings };

package/src/identity-document.ts

@@ -0,0 +1,86 @@
+import { Effect, Schema } from "effect";
+
+const optionalNullable = <S extends Schema.Top>(schema: S) =>
+  Schema.NullOr(schema).pipe(
+    Schema.optional,
+    Schema.withDecodingDefault(Effect.succeed(null))
+  );
+
+/**
+ * Schema for the EC2 instance identity document served at
+ * `/latest/dynamic/instance-identity/document`.
+ *
+ * Unknown keys are ignored so that fields AWS adds later do not break decoding.
+ *
+ * @since 0.1.0
+ */
+// oxlint-disable-next-line no-redeclare -- The decoded type below intentionally shares the schema's name.
+export const IdentityDocument = Schema.Struct({
+  accountId: Schema.String.check(Schema.isPattern(/^\d{12}$/u)).annotateKey({
+    description: "The ID of the AWS account that launched the instance.",
+  }),
+  architecture: Schema.Literals(["i386", "x86_64", "arm64"]).annotateKey({
+    description: "The architecture of the AMI used to launch the instance.",
+  }),
+  availabilityZone: Schema.NonEmptyString.annotateKey({
+    description: "The Availability Zone in which the instance is running.",
+  }),
+  billingProducts: optionalNullable(Schema.Array(Schema.String)).annotateKey({
+    description: "The billing products of the instance.",
+  }),
+  devpayProductCodes: optionalNullable(Schema.Array(Schema.String)).annotateKey(
+    { description: "Deprecated AWS DevPay product codes of the AMI." }
+  ),
+  imageId: Schema.String.check(
+    Schema.isPattern(/^ami-[0-9a-f]+$/iu)
+  ).annotateKey({
+    description: "The ID of the AMI used to launch the instance.",
+  }),
+  instanceId: Schema.String.check(
+    Schema.isPattern(/^i-[0-9a-f]+$/iu)
+  ).annotateKey({ description: "The ID of the instance." }),
+  instanceType: Schema.NonEmptyString.annotateKey({
+    description: "The instance type of the instance.",
+  }),
+  kernelId: optionalNullable(Schema.String).annotateKey({
+    description: "The ID of the kernel associated with the instance.",
+  }),
+  marketplaceProductCodes: optionalNullable(
+    Schema.Array(Schema.String)
+  ).annotateKey({
+    description: "The AWS Marketplace product codes of the AMI.",
+  }),
+  pendingTime: Schema.DateFromString.annotateKey({
+    description: "The date and time that the instance was launched.",
+  }),
+  privateIp: Schema.String.check(
+    Schema.isNonEmpty(),
+    Schema.isTrimmed()
+  ).annotateKey({
+    description:
+      "The private IPv4 address, or IPv6 address on IPv6-only instances.",
+  }),
+  ramdiskId: optionalNullable(Schema.String).annotateKey({
+    description: "The ID of the RAM disk associated with the instance.",
+  }),
+  region: Schema.String.check(
+    Schema.isPattern(/^[a-z]{2,}(?:-[a-z]+)+-\d+$/u)
+  ).annotateKey({
+    description: "The Region in which the instance is running.",
+  }),
+  version: Schema.String.check(
+    Schema.isPattern(/^\d{4}-\d{2}-\d{2}$/u)
+  ).annotateKey({
+    description: "The version of the identity document format.",
+  }),
+}).annotate({
+  identifier: "IdentityDocument",
+  title: "EC2 Instance Identity Document",
+});
+
+/**
+ * A decoded EC2 instance identity document.
+ *
+ * @since 0.1.0
+ */
+export type IdentityDocument = typeof IdentityDocument.Type;

package/src/index.ts

@@ -0,0 +1,66 @@
+/**
+ * Effect-native client for the AWS EC2 Instance Metadata Service (IMDS).
+ *
+ * The client speaks IMDSv2 only. Session tokens are fetched with `PUT
+ * /latest/api/token`, cached for slightly less than their TTL, and refreshed
+ * once when IMDS answers `401`. Every attempt has its own timeout, and transient
+ * failures are retried with jittered exponential backoff.
+ *
+ * The instance identity document is decoded against `IdentityDocument` and
+ * memoized after the first success. Failures are never cached, so a caller can
+ * try again later.
+ *
+ * Outside EC2 (local development, or a container beyond the IMDS hop limit)
+ * operations fail with a typed `AwsImdsError` rather than returning `undefined`.
+ * Apply `Effect.option` at the call site when the value is genuinely optional.
+ * With the defaults, an endpoint that never answers fails after about 3.2
+ * seconds (three 1 second attempts plus backoff); a refused connection fails
+ * within a fraction of a second.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as AwsImds from "@rc312/effect-aws-imds"
+ *
+ * const program = Effect.gen(function* () {
+ *   // Yield the Effect to obtain the decoded, memoized document.
+ *   const document = yield* AwsImds.identityDocument
+ *   // document.instanceType is already available without another request.
+ *   // This extra request demonstrates uncached reads with get(path).
+ *   const instanceType = yield* AwsImds.get("/latest/meta-data/instance-type")
+ *   return { region: document.region, instanceType }
+ * })
+ *
+ * const runnable = program.pipe(Effect.provide(AwsImds.layerFetch))
+ * ```
+ *
+ * @since 0.1.0
+ */
+export {
+  AwsImds,
+  type AwsImdsError,
+  get,
+  getSchema,
+  optional,
+} from "./aws-imds.ts";
+
+export {
+  AwsImdsConfig,
+  type AwsImdsOptions,
+  type AwsImdsSettings,
+  retryPolicy,
+} from "./config.ts";
+
+export { IdentityDocument } from "./identity-document.ts";
+
+export { identityDocument, InstanceIdentity } from "./instance-identity.ts";
+
+export { clearCache, layer, layerFetch } from "./layer.ts";
+
+export { AwsImdsToken } from "./token.ts";
+
+export { imdsTransport, withSessionToken } from "./transport.ts";
+
+export { AwsImdsMetadataError } from "./metadata-error.ts";
+
+export { AwsImdsTokenError } from "./token-error.ts";

package/src/instance-identity.ts

@@ -0,0 +1,63 @@
+import { Cache, Context, Duration, Effect, Layer, Schema } from "effect";
+
+import { AwsImds, decodeAt } from "./aws-imds.ts";
+import type { AwsImdsError } from "./aws-imds.ts";
+import { IdentityDocument } from "./identity-document.ts";
+import { cacheOnSuccess } from "./internal.ts";
+
+const IDENTITY_DOCUMENT_PATH = "/latest/dynamic/instance-identity/document";
+
+const decodeDocument = decodeAt(
+  IDENTITY_DOCUMENT_PATH,
+  Schema.fromJsonString(IdentityDocument)
+);
+
+/**
+ * The decoded instance identity document, memoized after the first success.
+ * Failures are not cached. Provide a fixed document with `Layer.succeed` to
+ * test code that depends on it without any HTTP.
+ *
+ * @since 0.1.0
+ */
+class InstanceIdentity extends Context.Service<
+  InstanceIdentity,
+  {
+    readonly document: Effect.Effect<IdentityDocument, AwsImdsError>;
+    readonly invalidate: Effect.Effect<void>;
+  }
+>()("@rc312/effect-aws-imds/InstanceIdentity") {
+  /** Reads the document through `AwsImds`. */
+  static readonly layer: Layer.Layer<InstanceIdentity, never, AwsImds> =
+    Layer.effect(
+      InstanceIdentity,
+      Effect.gen(function* make() {
+        const imds = yield* AwsImds;
+
+        const resolve = imds
+          .get(IDENTITY_DOCUMENT_PATH)
+          .pipe(
+            Effect.flatMap(decodeDocument),
+            Effect.withSpan("InstanceIdentity.resolve")
+          );
+
+        const documents = yield* Cache.makeWith(() => resolve, {
+          capacity: 1,
+          timeToLive: cacheOnSuccess(Duration.infinity),
+        });
+
+        return InstanceIdentity.of({
+          document: Cache.get(documents, IDENTITY_DOCUMENT_PATH),
+          invalidate: Cache.invalidate(documents, IDENTITY_DOCUMENT_PATH),
+        });
+      })
+    );
+}
+
+/**
+ * The memoized, decoded instance identity document.
+ *
+ * @since 0.1.0
+ */
+const identityDocument = InstanceIdentity.use((identity) => identity.document);
+
+export { identityDocument, InstanceIdentity };

package/src/internal.ts

@@ -0,0 +1,21 @@
+import { Duration, Exit } from "effect";
+import { HttpClientError } from "effect/http";
+
+// Keep only the message and status: client errors retain the request headers.
+const failureDetails = (cause: Error) => {
+  const status = HttpClientError.isHttpClientError(cause)
+    ? cause.response?.status
+    : undefined;
+
+  return status === undefined
+    ? { message: cause.message }
+    : { message: cause.message, status };
+};
+
+// `Effect.cachedWithTTL` would also cache failures; IMDS failures are transient.
+const cacheOnSuccess =
+  (ttl: Duration.Duration) =>
+  <A, E>(exit: Exit.Exit<A, E>) =>
+    Exit.isSuccess(exit) ? ttl : Duration.zero;
+
+export { cacheOnSuccess, failureDetails };

package/src/layer.ts

@@ -0,0 +1,36 @@
+import { Effect, Layer } from "effect";
+import { FetchHttpClient } from "effect/http";
+
+import { AwsImds } from "./aws-imds.ts";
+import { InstanceIdentity } from "./instance-identity.ts";
+import { AwsImdsToken } from "./token.ts";
+
+/**
+ * Provides `InstanceIdentity`, `AwsImds`, and `AwsImdsToken` from the
+ * `HttpClient` in the environment. Settings come from `AwsImdsConfig`.
+ *
+ * @since 0.1.0
+ */
+const layer = InstanceIdentity.layer.pipe(
+  Layer.provideMerge(AwsImds.layer),
+  Layer.provideMerge(AwsImdsToken.layer)
+);
+
+/**
+ * `layer` backed by the platform `fetch` through `FetchHttpClient`.
+ *
+ * @since 0.1.0
+ */
+const layerFetch = layer.pipe(Layer.provide(FetchHttpClient.layer));
+
+/**
+ * Discards the cached session token and identity document.
+ *
+ * @since 0.1.0
+ */
+const clearCache = Effect.andThen(
+  AwsImdsToken.use((token) => token.clear),
+  InstanceIdentity.use((identity) => identity.invalidate)
+);
+
+export { clearCache, layer, layerFetch };

package/src/metadata-error.ts

@@ -0,0 +1,21 @@
+import { Schema } from "effect";
+
+/**
+ * Failure to read or decode the metadata at `path`.
+ *
+ * `status` is the HTTP status when IMDS answered with a non-2xx response, for
+ * example `404` for a path that does not exist on this instance. Transport,
+ * timeout, and decoding failures have no `status`. The underlying request is
+ * not retained because its headers carry the session token.
+ *
+ * @since 0.1.0
+ */
+// oxlint-disable-next-line unicorn/throw-new-error -- TaggedError is a class factory.
+export class AwsImdsMetadataError extends Schema.TaggedError<
+  AwsImdsMetadataError,
+  { readonly brand: unique symbol }
+>()("AwsImdsMetadataError", {
+  message: Schema.String,
+  path: Schema.String,
+  status: Schema.optional(Schema.Int),
+}) {}

package/src/token-error.ts

@@ -0,0 +1,18 @@
+import { Schema } from "effect";
+
+/**
+ * Failure to obtain an IMDSv2 session token.
+ *
+ * `status` is the HTTP status when IMDS answered the token request with a
+ * non-2xx response. Transport, timeout, and decoding failures have no `status`.
+ *
+ * @since 0.1.0
+ */
+// oxlint-disable-next-line unicorn/throw-new-error -- TaggedError is a class factory.
+export class AwsImdsTokenError extends Schema.TaggedError<
+  AwsImdsTokenError,
+  { readonly brand: unique symbol }
+>()("AwsImdsTokenError", {
+  message: Schema.String,
+  status: Schema.optional(Schema.Int),
+}) {}

package/src/token.ts

@@ -0,0 +1,114 @@
+import {
+  Cache,
+  Context,
+  Duration,
+  Effect,
+  Layer,
+  Option,
+  Redacted,
+  Schema,
+} from "effect";
+import { HttpClient } from "effect/http";
+
+import { AwsImdsConfig } from "./config.ts";
+import { cacheOnSuccess, failureDetails } from "./internal.ts";
+import { AwsImdsTokenError } from "./token-error.ts";
+import { imdsTransport, TOKEN_HEADER } from "./transport.ts";
+
+const TOKEN_PATH = "/latest/api/token";
+const TOKEN_TTL_HEADER = "x-aws-ec2-metadata-token-ttl-seconds";
+const MIN_TTL_SECONDS = 1;
+const MAX_TTL_SECONDS = 21_600;
+const REFRESH_MARGIN = Duration.seconds(30);
+
+const decodeToken = Schema.decodeEffect(
+  Schema.NonEmptyString.annotate({ description: "IMDSv2 session token" })
+);
+
+const ttlSeconds = (ttl: Duration.Duration) =>
+  Math.min(
+    MAX_TTL_SECONDS,
+    Math.max(MIN_TTL_SECONDS, Math.floor(Duration.toSeconds(ttl)))
+  );
+
+// Refresh 30 seconds early, or halfway through a short-lived token.
+const refreshAfter = (ttl: Duration.Duration) =>
+  Duration.max(
+    Duration.subtract(ttl, REFRESH_MARGIN),
+    Duration.divideUnsafe(ttl, 2)
+  );
+
+const toTokenError = (cause: Error) =>
+  new AwsImdsTokenError(failureDetails(cause));
+
+/**
+ * IMDSv2 session tokens.
+ *
+ * - `get` returns the cached token, requesting one with `PUT /latest/api/token`
+ *   when none is cached or the cached one is close to expiry.
+ * - `invalidate(token)` discards `token` if it is still the cached one, so
+ *   concurrent reads that were all rejected trigger a single refresh.
+ * - `clear` discards the cached token unconditionally.
+ *
+ * Provide your own implementation with `Layer.succeed` to use a fixed token.
+ *
+ * @since 0.1.0
+ */
+class AwsImdsToken extends Context.Service<
+  AwsImdsToken,
+  {
+    readonly get: Effect.Effect<Redacted.Redacted<string>, AwsImdsTokenError>;
+    readonly invalidate: (
+      rejected: Redacted.Redacted<string>
+    ) => Effect.Effect<void>;
+    readonly clear: Effect.Effect<void>;
+  }
+>()("@rc312/effect-aws-imds/AwsImdsToken") {
+  /** Requests tokens through the `HttpClient`, configured by `AwsImdsConfig`. */
+  static readonly layer: Layer.Layer<
+    AwsImdsToken,
+    never,
+    HttpClient.HttpClient
+  > = Layer.effect(
+    AwsImdsToken,
+    Effect.gen(function* make() {
+      const settings = yield* AwsImdsConfig;
+      const seconds = ttlSeconds(settings.tokenTtl);
+
+      const client = (yield* HttpClient.HttpClient).pipe(
+        imdsTransport(settings)
+      );
+
+      const fetchToken = client
+        .put(TOKEN_PATH, { headers: { [TOKEN_TTL_HEADER]: String(seconds) } })
+        .pipe(
+          Effect.flatMap((response) => response.text),
+          Effect.flatMap((text) => decodeToken(text)),
+          Effect.map((token) => Redacted.make(token, { label: TOKEN_HEADER })),
+          Effect.mapError(toTokenError),
+          Effect.withSpan("AwsImdsToken.fetch")
+        );
+
+      const tokens = yield* Cache.makeWith(() => fetchToken, {
+        capacity: 1,
+        timeToLive: cacheOnSuccess(refreshAfter(Duration.seconds(seconds))),
+      });
+
+      const current = Cache.get(tokens, TOKEN_PATH);
+      const clear = Cache.invalidate(tokens, TOKEN_PATH);
+
+      return AwsImdsToken.of({
+        clear,
+        get: current,
+        invalidate: (rejected) =>
+          Cache.getSuccess(tokens, TOKEN_PATH).pipe(
+            Effect.flatMap((cached) =>
+              Option.contains(cached, rejected) ? clear : Effect.void
+            )
+          ),
+      });
+    })
+  );
+}
+
+export { AwsImdsToken };

package/src/transport.ts

@@ -0,0 +1,101 @@
+import { Effect, Redacted } from "effect";
+import {
+  Headers,
+  HttpClient,
+  HttpClientError,
+  HttpClientRequest,
+} from "effect/http";
+
+import type { AwsImdsSettings } from "./config.ts";
+import type { AwsImdsToken } from "./token.ts";
+
+const TOKEN_HEADER = "x-aws-ec2-metadata-token";
+const UNAUTHORIZED = 401;
+
+// Redacts the session token from client spans that capture request headers.
+const redactTokenHeader = Effect.updateService(
+  Headers.CurrentRedactedNames,
+  (names) => [...names, TOKEN_HEADER]
+);
+
+/**
+ * IMDS transport policy for any `HttpClient`: the endpoint as base URL, a
+ * timeout on each attempt including its text body, non-2xx statuses as errors,
+ * and transient retries on `settings.retrySchedule`.
+ *
+ * @since 0.1.0
+ */
+const imdsTransport =
+  (settings: AwsImdsSettings) =>
+  <E, R>(client: HttpClient.HttpClient.With<E, R>) =>
+    client.pipe(
+      HttpClient.mapRequest(HttpClientRequest.prependUrl(settings.endpoint)),
+      HttpClient.filterStatusOk,
+      // HTTP responses memoize their text, so callers can read it again after
+      // the complete download has succeeded within the attempt's deadline.
+      HttpClient.tap((response) => response.text),
+      HttpClient.transformResponse(Effect.timeout(settings.attemptTimeout)),
+      HttpClient.retryTransient({
+        schedule: settings.retrySchedule,
+        // Reading the text body can fail after headers have already arrived.
+        // Schema/JSON decoding happens outside this transport policy.
+        while: (error) =>
+          HttpClientError.isHttpClientError(error) &&
+          error.reason instanceof HttpClientError.DecodeError,
+      })
+    );
+
+const isUnauthorized = <E>(error: E) =>
+  HttpClientError.isHttpClientError(error) &&
+  error.response?.status === UNAUTHORIZED;
+
+/**
+ * Wraps a client so every request carries a session token. The token is
+ * resolved before the request, outside its timeout and transient retries; a
+ * `401` invalidates that token and the request runs once more with a new one.
+ *
+ * Apply it after `imdsTransport`: the transport's timeout and retries then
+ * cover each metadata request, while time spent obtaining the token does not
+ * count against them.
+ *
+ * @since 0.1.0
+ */
+const withSessionToken =
+  (token: AwsImdsToken["Service"]) =>
+  <E, R>(client: HttpClient.HttpClient.With<E, R>) => {
+    const attempt = (request: HttpClientRequest.HttpClientRequest) =>
+      token.get.pipe(
+        Effect.flatMap((sessionToken) =>
+          client
+            .execute(
+              HttpClientRequest.setHeader(
+                request,
+                TOKEN_HEADER,
+                Redacted.value(sessionToken)
+              )
+            )
+            .pipe(
+              redactTokenHeader,
+              Effect.tapError((failure) =>
+                isUnauthorized(failure)
+                  ? token.invalidate(sessionToken)
+                  : Effect.void
+              )
+            )
+        )
+      );
+
+    return HttpClient.makeWith(
+      (request: Effect.Effect<HttpClientRequest.HttpClientRequest>) =>
+        request.pipe(
+          Effect.flatMap((prepared) =>
+            attempt(prepared).pipe(
+              Effect.retry({ times: 1, while: isUnauthorized })
+            )
+          )
+        ),
+      Effect.succeed
+    );
+  };
+
+export { imdsTransport, TOKEN_HEADER, withSessionToken };