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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Callahan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,159 @@
-# Temporary Holding Version
+# @rc312/effect-aws-imds
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An **Effect-native client for the AWS EC2 Instance Metadata Service** (IMDSv2). It has no runtime dependencies besides its `effect` peer.
+
+```sh
+bun add @rc312/effect-aws-imds 'effect@^4.1.2'
+```
+
+## Usage
+
+```ts
+import * as AwsImds from "@rc312/effect-aws-imds";
+import { Effect } from "effect";
+
+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 {
+    accountId: document.accountId,
+    region: document.region,
+    instanceType,
+  };
+});
+
+Effect.runPromise(program.pipe(Effect.provide(AwsImds.layerFetch)));
+```
+
+`layerFetch` uses the platform `fetch`. Use `AwsImds.layer` instead to supply your own `HttpClient`, such as a Node or Bun platform client or a test double. Both are plain `Layer` values. Build one into your runtime (for example a single `ManagedRuntime` or one composed application layer) so the whole program shares one token cache and one identity document cache; each separate `Effect.provide` builds its own.
+
+## Composition
+
+The package is a small graph of services, each with its own layer:
+
+| Service | Provides | `layer` requires |
+| --- | --- | --- |
+| `AwsImdsConfig` | Settings (a `Context.Reference` with defaults) | — |
+| `AwsImdsToken` | `get`, `invalidate(token)`, and `clear` for IMDSv2 session tokens | `HttpClient` |
+| `AwsImds` | `get(path)`: uncached metadata reads with session auth | `HttpClient`, `AwsImdsToken` |
+| `InstanceIdentity` | `document` (memoized) and `invalidate` | `AwsImds` |
+
+The top-level `layer` (`AwsImds.layer` with a namespace import) composes the `AwsImdsToken`, `AwsImds`, and `InstanceIdentity` layers with `Layer.provideMerge`, so all three stay available to your program. Those layers read `AwsImdsConfig` while they are built. Each service also has its own `layer` static, such as `AwsImds.AwsImds.layer`, for building a different graph. Replace any one of them to change one concern:
+
+```ts
+import * as AwsImds from "@rc312/effect-aws-imds";
+import { Effect, Layer, Redacted } from "effect";
+
+// A fixed session token, for example one issued elsewhere.
+const StaticToken = Layer.succeed(
+  AwsImds.AwsImdsToken,
+  AwsImds.AwsImdsToken.of({
+    clear: Effect.void,
+    get: Effect.succeed(Redacted.make("token-issued-elsewhere")),
+    invalidate: () => Effect.void,
+  })
+);
+
+const Reads = AwsImds.AwsImds.layer.pipe(Layer.provide(StaticToken));
+```
+
+### Client combinators
+
+The HTTP policy is exposed as two `HttpClient` combinators, so you can build your own client around them:
+
+- `imdsTransport(settings)` applies the endpoint, buffers successful text bodies within the per-attempt timeout, treats non-2xx statuses as errors, and applies `retrySchedule`, including retries for interrupted body downloads.
+- `withSessionToken(token)` resolves a session token from an `AwsImdsToken` before each request, outside that request's timeout and retries, and refreshes it once after a `401`. Apply it after `imdsTransport`.
+
+```ts
+import * as AwsImds from "@rc312/effect-aws-imds";
+import { Effect } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+
+// An IMDS client that also tags every request with a trace id.
+const tracedImdsClient = (traceId: string) =>
+  Effect.gen(function* () {
+    const settings = yield* AwsImds.AwsImdsConfig;
+    const token = yield* AwsImds.AwsImdsToken;
+
+    return (yield* HttpClient.HttpClient).pipe(
+      AwsImds.imdsTransport(settings),
+      HttpClient.mapRequest(HttpClientRequest.setHeader("x-trace", traceId)),
+      AwsImds.withSessionToken(token)
+    );
+  });
+```
+
+Code that needs only the identity document can depend on `InstanceIdentity` and receive a fixed document from `Layer.succeed` in tests, with no HTTP at all.
+
+### Settings
+
+Provide settings with `Layer.provide`. A settings layer merged beside the IMDS layers is not used to build them, so they silently keep the defaults.
+
+```ts
+import * as AwsImds from "@rc312/effect-aws-imds";
+import { Config, Layer } from "effect";
+
+const ImdsLive = AwsImds.layerFetch.pipe(
+  Layer.provide(
+    AwsImds.AwsImdsConfig.layerConfig({
+      endpoint: Config.String("AWS_EC2_METADATA_SERVICE_ENDPOINT").pipe(
+        Config.withDefault("http://169.254.169.254")
+      ),
+      retrySchedule: Config.Int("IMDS_RETRIES").pipe(
+        Config.withDefault(2),
+        Config.map(AwsImds.retryPolicy)
+      ),
+    })
+  )
+);
+```
+
+| Setting | Default | Notes |
+| --- | --- | --- |
+| `endpoint` | `http://169.254.169.254` | Use `http://[fd00:ec2::254]` on IPv6-only instances. |
+| `tokenTtl` | `6 hours` | Clamped to 1 second through 6 hours. |
+| `attemptTimeout` | `1 second` | Applies to each HTTP attempt, including reading its response body. Token requests run before a read, outside its timeout. |
+| `retrySchedule` | `retryPolicy(2)` | A bounded `Schedule` (for example with `Schedule.upTo`), applied to timeouts, transport errors, and transient statuses (408, 429, 500, 502, 503, 504). It is the only bound on retries: an unbounded schedule retries forever when IMDS is unreachable. |
+
+`AwsImdsConfig.layer(options)` takes the same fields as plain values.
+
+## Reading metadata
+
+| Export | Description |
+| --- | --- |
+| `get(path)` | The raw text at a path such as `/latest/meta-data/instance-id`. |
+| `getSchema(path, codec)` | Reads `path` and decodes the text with `codec`, for example `Schema.fromJsonString(MySchema)`. Decode failures are `AwsImdsMetadataError`s for `path`. |
+| `optional` | A combinator that maps a `404` to `Option.none()` and a success to `Option.some`, keeping every other failure: `get(path).pipe(AwsImds.optional)`. |
+| `identityDocument` | The decoded instance identity document from `InstanceIdentity`. |
+| `clearCache` | Discards the cached session token and identity document. |
+| `retryPolicy(times)` | Jittered exponential backoff from 50 ms, bounded to `times` retries. Compose your own `Schedule` instead if you need a different policy. |
+| `IdentityDocument` | Schema for the identity document. Unknown keys are ignored. |
+| `AwsImdsTokenError` | Failure to obtain a session token, with a `message` and, for non-2xx responses, `status`. |
+| `AwsImdsMetadataError` | Failure to read or decode a path, with `path`, a sanitized `message` and, for non-2xx responses, `status`. |
+
+## Behavior
+
+- **IMDSv2 only.** Session tokens come from `PUT /latest/api/token`, are cached until 30 seconds before they expire (or half their TTL, if that is later), and are refreshed once when a read returns `401`. When several concurrent reads are rejected with the same token, only one replacement is requested.
+- **Retries.** Retries use jittered exponential backoff starting at 50 ms and honor `Retry-After`.
+- **Caching.** Only successful results are cached. A failed lookup is retried the next time it is requested.
+- **Outside EC2.** Operations fail with `AwsImdsTokenError` or `AwsImdsMetadataError` instead of returning `undefined`; use `Effect.option` if the value is optional. With the defaults, an endpoint that accepts connections but never answers fails after about 3.2 seconds (three 1-second attempts plus backoff); a refused connection fails within a fraction of a second. Lower `attemptTimeout` or use `retryPolicy(0)` to fail faster.
+
+- **Token handling.** The session token is held as a `Redacted` value. `x-aws-ec2-metadata-token` is added to `Headers.CurrentRedactedNames` for metadata requests, so client spans that capture request headers record it as `<redacted>`. Neither error type keeps the underlying HTTP request or its headers.
+
+## Example and end-to-end tests
+
+[`examples/instance-info`](examples/instance-info) is a CLI that uses the built package against a strict mock IMDS. Its end-to-end tests run the CLI as a real process for the healthy, throttled, token-expiry, malformed-document, unresponsive, and unreachable cases. See its [README](examples/instance-info/README.md) to run it by hand.
+
+## Development
+
+```sh
+bun run --cwd packages/effect-aws-imds build
+bun run --cwd packages/effect-aws-imds typecheck
+bun run --cwd packages/effect-aws-imds test
+```
+
+Unit tests use an in-memory `HttpClient`, `TestClock`, and a loopback server; they never contact a real metadata endpoint. The example's end-to-end tests run with `bun run --cwd packages/effect-aws-imds/examples/instance-info test`, and both suites run in `bun run check`.

package/dist/aws-imds.d.ts

@@ -0,0 +1,58 @@
+import { Context, Effect, Layer, Schema } from "effect";
+import { HttpClient } from "effect/http";
+import { AwsImdsMetadataError } from "./metadata-error.ts";
+import { AwsImdsTokenError } from "./token-error.ts";
+import { AwsImdsToken } from "./token.ts";
+/**
+ * Any failure produced by the IMDS services.
+ *
+ * @since 0.1.0
+ */
+type AwsImdsError = AwsImdsMetadataError | AwsImdsTokenError;
+declare const AwsImds_base: Context.ServiceClass<AwsImds, "@rc312/effect-aws-imds/AwsImds", {
+    readonly get: (path: string) => Effect.Effect<string, AwsImdsError>;
+}>;
+/**
+ * Reads instance metadata through IMDSv2. Reads are not cached.
+ *
+ * `get(path)` returns the raw text at a path such as
+ * `/latest/meta-data/instance-id`.
+ *
+ * @since 0.1.0
+ */
+declare class AwsImds extends AwsImds_base {
+    /** Reads through the `HttpClient` with tokens from `AwsImdsToken`. */
+    static readonly layer: Layer.Layer<AwsImds, never, AwsImdsToken | HttpClient.HttpClient>;
+}
+/** Decodes metadata text with `codec`, attributing failures to `path`. */
+declare const decodeAt: <A, RD>(path: string, codec: Schema.Codec<A, string, RD>) => (text: string) => Effect.Effect<A, AwsImdsMetadataError, RD>;
+/**
+ * Reads the raw text at a metadata path.
+ *
+ * @since 0.1.0
+ */
+declare const get: (path: string) => Effect.Effect<string, AwsImdsError, AwsImds>;
+/**
+ * Reads a metadata path and decodes its text with `codec`, for example
+ * `Schema.fromJsonString(MySchema)` for a JSON document.
+ *
+ * @since 0.1.0
+ */
+declare const getSchema: <A, RD>(path: string, codec: Schema.Codec<A, string, RD>) => Effect.Effect<A, AwsImdsError, RD | AwsImds>;
+/**
+ * Turns a `404` from IMDS into `Option.none()` and a success into
+ * `Option.some`. Every other failure is kept.
+ *
+ * @example
+ * ```ts
+ * const action = AwsImds.get("/latest/meta-data/spot/instance-action").pipe(
+ *   AwsImds.optional
+ * )
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare const optional: <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<import("effect/Option").Option<never> | import("effect/Option").Option<A>, E, R>;
+export { AwsImds, decodeAt, get, getSchema, optional };
+export type { AwsImdsError };
+//# sourceMappingURL=aws-imds.d.ts.map

package/dist/aws-imds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aws-imds.d.ts","sourceRoot":"","sources":["../src/aws-imds.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAQ,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK1C;;;;GAIG;AACH,KAAK,YAAY,GAAG,oBAAoB,GAAG,iBAAiB,CAAC;;kBAoB3C,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;;AAXvE;;;;;;;GAOG;AACH,cAAM,OAAQ,SAAQ,YAKe;IACnC,sEAAsE;IACtE,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAChC,OAAO,EACP,KAAK,EACL,YAAY,GAAG,UAAU,CAAC,UAAU,CACrC,CAsBC;CACH;AAED,0EAA0E;AAC1E,QAAA,MAAM,QAAQ,GAAI,CAAC,EAAE,EAAE,QAAQ,MAAM,SAAS,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,iEAItE,CAAC;AAEJ;;;;GAIG;AACH,QAAA,MAAM,GAAG,SAAU,MAAM,iDAA0C,CAAC;AAEpE;;;;;GAKG;AACH,QAAA,MAAM,SAAS,GAAI,CAAC,EAAE,EAAE,QAAQ,MAAM,SAAS,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,iDACnB,CAAC;AAKxD;;;;;;;;;;;;GAYG;AACH,QAAA,MAAM,QAAQ,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,mGAIpD,CAAC;AAEJ,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;AAEvD,YAAY,EAAE,YAAY,EAAE,CAAC"}

package/dist/aws-imds.js

@@ -0,0 +1,65 @@
+import { Context, Effect, flow, Layer, Schema } from "effect";
+import { HttpClient } from "effect/http";
+import { AwsImdsConfig } from "./config.js";
+import { failureDetails } from "./internal.js";
+import { AwsImdsMetadataError } from "./metadata-error.js";
+import { AwsImdsTokenError } from "./token-error.js";
+import { AwsImdsToken } from "./token.js";
+import { imdsTransport, withSessionToken } from "./transport.js";
+const NOT_FOUND = 404;
+const metadataError = (path) => (cause) => new AwsImdsMetadataError({ ...failureDetails(cause), path });
+// Token failures surface as themselves; everything else is about `path`.
+const toImdsError = (path) => (cause) => cause instanceof AwsImdsTokenError ? cause : metadataError(path)(cause);
+/**
+ * Reads instance metadata through IMDSv2. Reads are not cached.
+ *
+ * `get(path)` returns the raw text at a path such as
+ * `/latest/meta-data/instance-id`.
+ *
+ * @since 0.1.0
+ */
+class AwsImds extends Context.Service()("@rc312/effect-aws-imds/AwsImds") {
+    /** Reads through the `HttpClient` with tokens from `AwsImdsToken`. */
+    static layer = Layer.effect(AwsImds, Effect.gen(function* make() {
+        const settings = yield* AwsImdsConfig;
+        const token = yield* AwsImdsToken;
+        const client = (yield* HttpClient.HttpClient).pipe(imdsTransport(settings), withSessionToken(token));
+        return AwsImds.of({
+            get: (path) => client.get(path).pipe(Effect.flatMap((response) => response.text), Effect.mapError(toImdsError(path)), Effect.withSpan("AwsImds.get", {
+                attributes: { "aws.imds.path": path },
+            })),
+        });
+    }));
+}
+/** Decodes metadata text with `codec`, attributing failures to `path`. */
+const decodeAt = (path, codec) => flow((text) => Schema.decodeEffect(codec)(text), Effect.mapError(metadataError(path)));
+/**
+ * Reads the raw text at a metadata path.
+ *
+ * @since 0.1.0
+ */
+const get = (path) => AwsImds.use((imds) => imds.get(path));
+/**
+ * Reads a metadata path and decodes its text with `codec`, for example
+ * `Schema.fromJsonString(MySchema)` for a JSON document.
+ *
+ * @since 0.1.0
+ */
+const getSchema = (path, codec) => get(path).pipe(Effect.flatMap(decodeAt(path, codec)));
+const isNotFound = (error) => error instanceof AwsImdsMetadataError && error.status === NOT_FOUND;
+/**
+ * Turns a `404` from IMDS into `Option.none()` and a success into
+ * `Option.some`. Every other failure is kept.
+ *
+ * @example
+ * ```ts
+ * const action = AwsImds.get("/latest/meta-data/spot/instance-action").pipe(
+ *   AwsImds.optional
+ * )
+ * ```
+ *
+ * @since 0.1.0
+ */
+const optional = (self) => self.pipe(Effect.asSome, Effect.catchIf(isNotFound, () => Effect.succeedNone));
+export { AwsImds, decodeAt, get, getSchema, optional };
+//# sourceMappingURL=aws-imds.js.map

package/dist/aws-imds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aws-imds.js","sourceRoot":"","sources":["../src/aws-imds.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,64 @@
+import { Config, Context, Duration, Layer, Schedule } from "effect";
+/**
+ * The default retry policy: jittered exponential backoff from 50 ms, bounded
+ * to `times` retries after the first attempt.
+ *
+ * @since 0.1.0
+ */
+declare const retryPolicy: (times: number) => Schedule.Schedule<Duration.Duration, unknown, never, never>;
+/**
+ * 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;
+}
+declare const AwsImdsConfig_base: Context.Reference<AwsImdsSettings>;
+/**
+ * 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
+ */
+declare class AwsImdsConfig extends AwsImdsConfig_base {
+    /** Overrides the given settings and keeps defaults for the rest. */
+    static readonly layer: (options: AwsImdsOptions) => Layer.Layer<never, never, never>;
+    /** Reads settings from `Config`, field by field or as one `Config`. */
+    static readonly layerConfig: (config: Config.Wrap<AwsImdsOptions>) => Layer.Layer<never, Config.ConfigError, never>;
+}
+export { AwsImdsConfig, retryPolicy };
+export type { AwsImdsOptions, AwsImdsSettings };
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAU,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAI5E;;;;;GAKG;AACH,QAAA,MAAM,WAAW,UAAW,MAAM,gEAI/B,CAAC;AAEJ;;;;GAIG;AACH,UAAU,eAAe;IACvB,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC;IACrC,gDAAgD;IAChD,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,QAAQ,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;CACpD;AAED;;;;;GAKG;AACH,UAAU,cAAc;IACtB,iGAAiG;IACjG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,2BAA2B;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAC;IAC/C,4BAA4B;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAC;IACrD,uFAAuF;IACvF,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC;CACjE;;AAkBD;;;;;;;GAOG;AACH,cAAM,aAAc,SAAQ,kBAG3B;IACC,oEAAoE;IACpE,MAAM,CAAC,QAAQ,CAAC,KAAK,YAAa,cAAc,sCACI;IAEpD,uEAAuE;IACvE,MAAM,CAAC,QAAQ,CAAC,WAAW,WAAY,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,mDACQ;CAC3E;AAED,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,CAAC;AAEtC,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC"}

package/dist/config.js

@@ -0,0 +1,37 @@
+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) => Schedule.exponential(RETRY_BASE_DELAY).pipe(Schedule.jittered, Schedule.upTo({ times }));
+const defaults = {
+    attemptTimeout: Duration.seconds(1),
+    endpoint: "http://169.254.169.254",
+    retrySchedule: retryPolicy(2),
+    tokenTtl: Duration.hours(6),
+};
+const resolve = (options) => ({
+    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("@rc312/effect-aws-imds/AwsImdsConfig", { defaultValue: () => defaults }) {
+    /** Overrides the given settings and keeps defaults for the rest. */
+    static layer = (options) => Layer.sync(AwsImdsConfig, () => resolve(options));
+    /** Reads settings from `Config`, field by field or as one `Config`. */
+    static layerConfig = (config) => Layer.effect(AwsImdsConfig, Effect.map(Config.unwrap(config), resolve));
+}
+export { AwsImdsConfig, retryPolicy };
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAE5E,MAAM,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,WAAW,GAAG,CAAC,KAAa,EAAE,EAAE,CACpC,QAAQ,CAAC,WAAW,CAAC,gBAAgB,CAAC,CAAC,IAAI,CACzC,QAAQ,CAAC,QAAQ,EACjB,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CACzB,CAAC;AA0CJ,MAAM,QAAQ,GAAoB;IAChC,cAAc,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACnC,QAAQ,EAAE,wBAAwB;IAClC,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC;IAC7B,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;CAC5B,CAAC;AAEF,MAAM,OAAO,GAAG,CAAC,OAAuB,EAAmB,EAAE,CAAC,CAAC;IAC7D,cAAc,EAAE,QAAQ,CAAC,eAAe,CACtC,OAAO,CAAC,cAAc,IAAI,QAAQ,CAAC,cAAc,CAClD;IACD,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ;IAC/C,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,QAAQ,CAAC,aAAa;IAC9D,QAAQ,EAAE,QAAQ,CAAC,eAAe,CAAC,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ,CAAC;CAC1E,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,aAAc,SAAQ,OAAO,CAAC,SAAS,CAC3C,sCAAsC,EACtC,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE,CACjC;IACC,oEAAoE;IACpE,MAAM,CAAU,KAAK,GAAG,CAAC,OAAuB,EAAE,EAAE,CAClD,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAEpD,uEAAuE;IACvE,MAAM,CAAU,WAAW,GAAG,CAAC,MAAmC,EAAE,EAAE,CACpE,KAAK,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3E;AAED,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,CAAC"}

package/dist/identity-document.d.ts

@@ -0,0 +1,33 @@
+import { Schema } from "effect";
+/**
+ * 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
+ */
+export declare const IdentityDocument: Schema.Struct<{
+    readonly accountId: Schema.String;
+    readonly architecture: Schema.Literals<readonly ["i386", "x86_64", "arm64"]>;
+    readonly availabilityZone: Schema.NonEmptyString;
+    readonly billingProducts: Schema.withDecodingDefault<Schema.optional<Schema.NullOr<Schema.$Array<Schema.String>>>, never>;
+    readonly devpayProductCodes: Schema.withDecodingDefault<Schema.optional<Schema.NullOr<Schema.$Array<Schema.String>>>, never>;
+    readonly imageId: Schema.String;
+    readonly instanceId: Schema.String;
+    readonly instanceType: Schema.NonEmptyString;
+    readonly kernelId: Schema.withDecodingDefault<Schema.optional<Schema.NullOr<Schema.String>>, never>;
+    readonly marketplaceProductCodes: Schema.withDecodingDefault<Schema.optional<Schema.NullOr<Schema.$Array<Schema.String>>>, never>;
+    readonly pendingTime: Schema.DateFromString;
+    readonly privateIp: Schema.String;
+    readonly ramdiskId: Schema.withDecodingDefault<Schema.optional<Schema.NullOr<Schema.String>>, never>;
+    readonly region: Schema.String;
+    readonly version: Schema.String;
+}>;
+/**
+ * A decoded EC2 instance identity document.
+ *
+ * @since 0.1.0
+ */
+export type IdentityDocument = typeof IdentityDocument.Type;
+//# sourceMappingURL=identity-document.d.ts.map

package/dist/identity-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-document.d.ts","sourceRoot":"","sources":["../src/identity-document.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAC;AAQxC;;;;;;;GAOG;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;EA6D3B,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAC"}

package/dist/identity-document.js

@@ -0,0 +1,58 @@
+import { Effect, Schema } from "effect";
+const optionalNullable = (schema) => 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",
+});
+//# sourceMappingURL=identity-document.js.map

package/dist/identity-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-document.js","sourceRoot":"","sources":["../src/identity-document.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAExC,MAAM,gBAAgB,GAAG,CAAuB,MAAS,EAAE,EAAE,CAC3D,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CACxB,MAAM,CAAC,QAAQ,EACf,MAAM,CAAC,mBAAmB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CACjD,CAAC;AAEJ;;;;;;;GAOG;AACH,0GAA0G;AAC1G,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5C,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC;QACxE,WAAW,EAAE,uDAAuD;KACrE,CAAC;IACF,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;QACrE,WAAW,EAAE,0DAA0D;KACxE,CAAC;IACF,gBAAgB,EAAE,MAAM,CAAC,cAAc,CAAC,WAAW,CAAC;QAClD,WAAW,EAAE,yDAAyD;KACvE,CAAC;IACF,eAAe,EAAE,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;QACzE,WAAW,EAAE,uCAAuC;KACrD,CAAC;IACF,kBAAkB,EAAE,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAC3E,EAAE,WAAW,EAAE,iDAAiD,EAAE,CACnE;IACD,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAC1B,MAAM,CAAC,SAAS,CAAC,mBAAmB,CAAC,CACtC,CAAC,WAAW,CAAC;QACZ,WAAW,EAAE,gDAAgD;KAC9D,CAAC;IACF,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAC7B,MAAM,CAAC,SAAS,CAAC,iBAAiB,CAAC,CACpC,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,yBAAyB,EAAE,CAAC;IACzD,YAAY,EAAE,MAAM,CAAC,cAAc,CAAC,WAAW,CAAC;QAC9C,WAAW,EAAE,oCAAoC;KAClD,CAAC;IACF,QAAQ,EAAE,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC;QACpD,WAAW,EAAE,oDAAoD;KAClE,CAAC;IACF,uBAAuB,EAAE,gBAAgB,CACvC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAC5B,CAAC,WAAW,CAAC;QACZ,WAAW,EAAE,+CAA+C;KAC7D,CAAC;IACF,WAAW,EAAE,MAAM,CAAC,cAAc,CAAC,WAAW,CAAC;QAC7C,WAAW,EAAE,mDAAmD;KACjE,CAAC;IACF,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAC5B,MAAM,CAAC,UAAU,EAAE,EACnB,MAAM,CAAC,SAAS,EAAE,CACnB,CAAC,WAAW,CAAC;QACZ,WAAW,EACT,mEAAmE;KACtE,CAAC;IACF,SAAS,EAAE,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC;QACrD,WAAW,EAAE,sDAAsD;KACpE,CAAC;IACF,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CACzB,MAAM,CAAC,SAAS,CAAC,8BAA8B,CAAC,CACjD,CAAC,WAAW,CAAC;QACZ,WAAW,EAAE,8CAA8C;KAC5D,CAAC;IACF,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAC1B,MAAM,CAAC,SAAS,CAAC,sBAAsB,CAAC,CACzC,CAAC,WAAW,CAAC;QACZ,WAAW,EAAE,8CAA8C;KAC5D,CAAC;CACH,CAAC,CAAC,QAAQ,CAAC;IACV,UAAU,EAAE,kBAAkB;IAC9B,KAAK,EAAE,gCAAgC;CACxC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EACL,OAAO,EACP,KAAK,YAAY,EACjB,GAAG,EACH,SAAS,EACT,QAAQ,GACT,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE5E,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,48 @@
+/**
+ * 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, get, getSchema, optional, } from "./aws-imds.js";
+export { AwsImdsConfig, retryPolicy, } from "./config.js";
+export { IdentityDocument } from "./identity-document.js";
+export { identityDocument, InstanceIdentity } from "./instance-identity.js";
+export { clearCache, layer, layerFetch } from "./layer.js";
+export { AwsImdsToken } from "./token.js";
+export { imdsTransport, withSessionToken } from "./transport.js";
+export { AwsImdsMetadataError } from "./metadata-error.js";
+export { AwsImdsTokenError } from "./token-error.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EACL,OAAO,EAEP,GAAG,EACH,SAAS,EACT,QAAQ,GACT,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,aAAa,EAGb,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE5E,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}