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

package/dist/instance-identity.d.ts

@@ -0,0 +1,43 @@
+import { Context, Effect, Layer } from "effect";
+import { AwsImds } from "./aws-imds.ts";
+import type { AwsImdsError } from "./aws-imds.ts";
+import { IdentityDocument } from "./identity-document.ts";
+declare const InstanceIdentity_base: Context.ServiceClass<InstanceIdentity, "@rc312/effect-aws-imds/InstanceIdentity", {
+    readonly document: Effect.Effect<IdentityDocument, AwsImdsError>;
+    readonly invalidate: Effect.Effect<void>;
+}>;
+/**
+ * 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
+ */
+declare class InstanceIdentity extends InstanceIdentity_base {
+    /** Reads the document through `AwsImds`. */
+    static readonly layer: Layer.Layer<InstanceIdentity, never, AwsImds>;
+}
+/**
+ * The memoized, decoded instance identity document.
+ *
+ * @since 0.1.0
+ */
+declare const identityDocument: Effect.Effect<{
+    readonly accountId: string;
+    readonly architecture: "arm64" | "i386" | "x86_64";
+    readonly availabilityZone: string;
+    readonly billingProducts?: readonly string[] | null | undefined;
+    readonly devpayProductCodes?: readonly string[] | null | undefined;
+    readonly imageId: string;
+    readonly instanceId: string;
+    readonly instanceType: string;
+    readonly kernelId?: string | null | undefined;
+    readonly marketplaceProductCodes?: readonly string[] | null | undefined;
+    readonly pendingTime: Date;
+    readonly privateIp: string;
+    readonly ramdiskId?: string | null | undefined;
+    readonly region: string;
+    readonly version: string;
+}, AwsImdsError, InstanceIdentity>;
+export { identityDocument, InstanceIdentity };
+//# sourceMappingURL=instance-identity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instance-identity.d.ts","sourceRoot":"","sources":["../src/instance-identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,OAAO,EAAY,MAAM,EAAE,KAAK,EAAU,MAAM,QAAQ,CAAC;AAEzE,OAAO,EAAE,OAAO,EAAY,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;;uBAoBnC,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE,YAAY,CAAC;yBAC3C,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;;AAX5C;;;;;;GAMG;AACH,cAAM,gBAAiB,SAAQ,qBAMe;IAC5C,4CAA4C;IAC5C,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,gBAAgB,EAAE,KAAK,EAAE,OAAO,CAAC,CAuBhE;CACL;AAED;;;;GAIG;AACH,QAAA,MAAM,gBAAgB;;;;;;;;;;;;;;;;kCAAwD,CAAC;AAE/E,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/instance-identity.js

@@ -0,0 +1,38 @@
+import { Cache, Context, Duration, Effect, Layer, Schema } from "effect";
+import { AwsImds, decodeAt } from "./aws-imds.js";
+import { IdentityDocument } from "./identity-document.js";
+import { cacheOnSuccess } from "./internal.js";
+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()("@rc312/effect-aws-imds/InstanceIdentity") {
+    /** Reads the document through `AwsImds`. */
+    static layer = 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 };
+//# sourceMappingURL=instance-identity.js.map

package/dist/instance-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-identity.js","sourceRoot":"","sources":["../src/instance-identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEzE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,MAAM,sBAAsB,GAAG,4CAA4C,CAAC;AAE5E,MAAM,cAAc,GAAG,QAAQ,CAC7B,sBAAsB,EACtB,MAAM,CAAC,cAAc,CAAC,gBAAgB,CAAC,CACxC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,gBAAiB,SAAQ,OAAO,CAAC,OAAO,EAM3C,CAAC,yCAAyC,CAAC;IAC5C,4CAA4C;IAC5C,MAAM,CAAU,KAAK,GACnB,KAAK,CAAC,MAAM,CACV,gBAAgB,EAChB,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI;QACvB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC;QAE5B,MAAM,OAAO,GAAG,IAAI;aACjB,GAAG,CAAC,sBAAsB,CAAC;aAC3B,IAAI,CACH,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,EAC9B,MAAM,CAAC,QAAQ,CAAC,0BAA0B,CAAC,CAC5C,CAAC;QAEJ,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE;YACrD,QAAQ,EAAE,CAAC;YACX,UAAU,EAAE,cAAc,CAAC,QAAQ,CAAC,QAAQ,CAAC;SAC9C,CAAC,CAAC;QAEH,OAAO,gBAAgB,CAAC,EAAE,CAAC;YACzB,QAAQ,EAAE,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,sBAAsB,CAAC;YACtD,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,SAAS,EAAE,sBAAsB,CAAC;SAChE,CAAC,CAAC;IACL,CAAC,CAAC,CACH,CAAC;CACL;AAED;;;;GAIG;AACH,MAAM,gBAAgB,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAE/E,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/internal.d.ts

@@ -0,0 +1,11 @@
+import { Duration, Exit } from "effect";
+declare const failureDetails: (cause: Error) => {
+    message: string;
+    status?: never;
+} | {
+    message: string;
+    status: number;
+};
+declare const cacheOnSuccess: (ttl: Duration.Duration) => <A, E>(exit: Exit.Exit<A, E>) => Duration.Duration;
+export { cacheOnSuccess, failureDetails };
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAIxC,QAAA,MAAM,cAAc,UAAW,KAAK;;;;;;CAQnC,CAAC;AAGF,QAAA,MAAM,cAAc,QACZ,QAAQ,CAAC,QAAQ,MACtB,CAAC,EAAE,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,sBACgB,CAAC;AAE/C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC"}

package/dist/internal.js

@@ -0,0 +1,15 @@
+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) => {
+    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) => (exit) => Exit.isSuccess(exit) ? ttl : Duration.zero;
+export { cacheOnSuccess, failureDetails };
+//# sourceMappingURL=internal.js.map

package/dist/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,8EAA8E;AAC9E,MAAM,cAAc,GAAG,CAAC,KAAY,EAAE,EAAE;IACtC,MAAM,MAAM,GAAG,eAAe,CAAC,iBAAiB,CAAC,KAAK,CAAC;QACrD,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM;QACxB,CAAC,CAAC,SAAS,CAAC;IAEd,OAAO,MAAM,KAAK,SAAS;QACzB,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE;QAC5B,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;AACzC,CAAC,CAAC;AAEF,iFAAiF;AACjF,MAAM,cAAc,GAClB,CAAC,GAAsB,EAAE,EAAE,CAC3B,CAAO,IAAqB,EAAE,EAAE,CAC9B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;AAE/C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC"}

package/dist/layer.d.ts

@@ -0,0 +1,25 @@
+import { Effect, Layer } from "effect";
+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
+ */
+declare const layer: Layer.Layer<AwsImds | AwsImdsToken | InstanceIdentity, never, import("effect/http/HttpClient").HttpClient>;
+/**
+ * `layer` backed by the platform `fetch` through `FetchHttpClient`.
+ *
+ * @since 0.1.0
+ */
+declare const layerFetch: Layer.Layer<AwsImds | AwsImdsToken | InstanceIdentity, never, never>;
+/**
+ * Discards the cached session token and identity document.
+ *
+ * @since 0.1.0
+ */
+declare const clearCache: Effect.Effect<void, never, AwsImdsToken | InstanceIdentity>;
+export { clearCache, layer, layerFetch };
+//# sourceMappingURL=layer.d.ts.map

package/dist/layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layer.d.ts","sourceRoot":"","sources":["../src/layer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;GAKG;AACH,QAAA,MAAM,KAAK,4GAGV,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,UAAU,sEAAmD,CAAC;AAEpE;;;;GAIG;AACH,QAAA,MAAM,UAAU,6DAGf,CAAC;AAEF,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC"}

package/dist/layer.js

@@ -0,0 +1,26 @@
+import { Effect, Layer } from "effect";
+import { FetchHttpClient } from "effect/http";
+import { AwsImds } from "./aws-imds.js";
+import { InstanceIdentity } from "./instance-identity.js";
+import { AwsImdsToken } from "./token.js";
+/**
+ * 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 };
+//# sourceMappingURL=layer.js.map

package/dist/layer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layer.js","sourceRoot":"","sources":["../src/layer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,KAAK,GAAG,gBAAgB,CAAC,KAAK,CAAC,IAAI,CACvC,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,EACjC,KAAK,CAAC,YAAY,CAAC,YAAY,CAAC,KAAK,CAAC,CACvC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;AAEpE;;;;GAIG;AACH,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAC/B,YAAY,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EACxC,gBAAgB,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CACxD,CAAC;AAEF,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC"}

package/dist/metadata-error.d.ts

@@ -0,0 +1,22 @@
+import { Schema } from "effect";
+declare const AwsImdsMetadataError_base: Schema.Class<AwsImdsMetadataError, Schema.TaggedStruct<"AwsImdsMetadataError", {
+    readonly message: Schema.String;
+    readonly path: Schema.String;
+    readonly status: Schema.optional<Schema.Int>;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+/**
+ * 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
+ */
+export declare class AwsImdsMetadataError extends AwsImdsMetadataError_base {
+}
+export {};
+//# sourceMappingURL=metadata-error.d.ts.map

package/dist/metadata-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-error.d.ts","sourceRoot":"","sources":["../src/metadata-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;;;;;;oBAeZ,OAAO,MAAM;;AAbjC;;;;;;;;;GASG;AAEH,qBAAa,oBAAqB,SAAQ,yBAOxC;CAAG"}

package/dist/metadata-error.js

@@ -0,0 +1,19 @@
+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", {
+    message: Schema.String,
+    path: Schema.String,
+    status: Schema.optional(Schema.Int),
+}) {
+}
+//# sourceMappingURL=metadata-error.js.map

package/dist/metadata-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-error.js","sourceRoot":"","sources":["../src/metadata-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC;;;;;;;;;GASG;AACH,sFAAsF;AACtF,MAAM,OAAO,oBAAqB,SAAQ,MAAM,CAAC,WAAW,EAGzD,CAAC,sBAAsB,EAAE;IAC1B,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,IAAI,EAAE,MAAM,CAAC,MAAM;IACnB,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC;CACpC,CAAC;CAAG"}

package/dist/token-error.d.ts

@@ -0,0 +1,19 @@
+import { Schema } from "effect";
+declare const AwsImdsTokenError_base: Schema.Class<AwsImdsTokenError, Schema.TaggedStruct<"AwsImdsTokenError", {
+    readonly message: Schema.String;
+    readonly status: Schema.optional<Schema.Int>;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+/**
+ * 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
+ */
+export declare class AwsImdsTokenError extends AwsImdsTokenError_base {
+}
+export {};
+//# sourceMappingURL=token-error.d.ts.map

package/dist/token-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-error.d.ts","sourceRoot":"","sources":["../src/token-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;;;;;oBAaZ,OAAO,MAAM;;AAXjC;;;;;;;GAOG;AAEH,qBAAa,iBAAkB,SAAQ,sBAMrC;CAAG"}

package/dist/token-error.js

@@ -0,0 +1,16 @@
+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", {
+    message: Schema.String,
+    status: Schema.optional(Schema.Int),
+}) {
+}
+//# sourceMappingURL=token-error.js.map

package/dist/token-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-error.js","sourceRoot":"","sources":["../src/token-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC;;;;;;;GAOG;AACH,sFAAsF;AACtF,MAAM,OAAO,iBAAkB,SAAQ,MAAM,CAAC,WAAW,EAGtD,CAAC,mBAAmB,EAAE;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC;CACpC,CAAC;CAAG"}

package/dist/token.d.ts

@@ -0,0 +1,27 @@
+import { Context, Effect, Layer, Redacted } from "effect";
+import { HttpClient } from "effect/http";
+import { AwsImdsTokenError } from "./token-error.ts";
+declare const AwsImdsToken_base: Context.ServiceClass<AwsImdsToken, "@rc312/effect-aws-imds/AwsImdsToken", {
+    readonly get: Effect.Effect<Redacted.Redacted<string>, AwsImdsTokenError>;
+    readonly invalidate: (rejected: Redacted.Redacted<string>) => Effect.Effect<void>;
+    readonly clear: Effect.Effect<void>;
+}>;
+/**
+ * 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
+ */
+declare class AwsImdsToken extends AwsImdsToken_base {
+    /** Requests tokens through the `HttpClient`, configured by `AwsImdsConfig`. */
+    static readonly layer: Layer.Layer<AwsImdsToken, never, HttpClient.HttpClient>;
+}
+export { AwsImdsToken };
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,OAAO,EAEP,MAAM,EACN,KAAK,EAEL,QAAQ,EAET,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;;kBA6CnC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;yBACpD,CACnB,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,KAChC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;oBACR,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;;AApBvC;;;;;;;;;;;;GAYG;AACH,cAAM,YAAa,SAAQ,iBASe;IACxC,+EAA+E;IAC/E,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAChC,YAAY,EACZ,KAAK,EACL,UAAU,CAAC,UAAU,CACtB,CAuCC;CACH;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/token.js

@@ -0,0 +1,53 @@
+import { Cache, Context, Duration, Effect, Layer, Option, Redacted, Schema, } from "effect";
+import { HttpClient } from "effect/http";
+import { AwsImdsConfig } from "./config.js";
+import { cacheOnSuccess, failureDetails } from "./internal.js";
+import { AwsImdsTokenError } from "./token-error.js";
+import { imdsTransport, TOKEN_HEADER } from "./transport.js";
+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) => 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.max(Duration.subtract(ttl, REFRESH_MARGIN), Duration.divideUnsafe(ttl, 2));
+const toTokenError = (cause) => 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()("@rc312/effect-aws-imds/AwsImdsToken") {
+    /** Requests tokens through the `HttpClient`, configured by `AwsImdsConfig`. */
+    static layer = 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 };
+//# sourceMappingURL=token.js.map

package/dist/token.js.map

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

package/dist/transport.d.ts

@@ -0,0 +1,26 @@
+import { HttpClient, HttpClientError } from "effect/http";
+import type { AwsImdsSettings } from "./config.ts";
+import type { AwsImdsToken } from "./token.ts";
+declare const TOKEN_HEADER = "x-aws-ec2-metadata-token";
+/**
+ * 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
+ */
+declare const imdsTransport: (settings: AwsImdsSettings) => <E, R>(client: HttpClient.HttpClient.With<E, R>) => HttpClient.HttpClient.With<E | HttpClientError.HttpClientError | import("effect/Cause").TimeoutError, R>;
+/**
+ * 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
+ */
+declare const withSessionToken: (token: AwsImdsToken["Service"]) => <E, R>(client: HttpClient.HttpClient.With<E, R>) => HttpClient.HttpClient.With<E | import("./token-error.ts").AwsImdsTokenError, R>;
+export { imdsTransport, TOKEN_HEADER, withSessionToken };
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,UAAU,EACV,eAAe,EAEhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,QAAA,MAAM,YAAY,6BAA6B,CAAC;AAShD;;;;;;GAMG;AACH,QAAA,MAAM,aAAa,aACN,eAAe,MACzB,CAAC,EAAE,CAAC,UAAU,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,6GAgB5C,CAAC;AAMN;;;;;;;;;;GAUG;AACH,QAAA,MAAM,gBAAgB,UACZ,YAAY,CAAC,SAAS,CAAC,MAC9B,CAAC,EAAE,CAAC,UAAU,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,oFAkC9C,CAAC;AAEJ,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/transport.js

@@ -0,0 +1,46 @@
+import { Effect, Redacted } from "effect";
+import { Headers, HttpClient, HttpClientError, HttpClientRequest, } from "effect/http";
+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) => (client) => 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 = (error) => 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) => (client) => {
+    const attempt = (request) => 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) => request.pipe(Effect.flatMap((prepared) => attempt(prepared).pipe(Effect.retry({ times: 1, while: isUnauthorized })))), Effect.succeed);
+};
+export { imdsTransport, TOKEN_HEADER, withSessionToken };
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EACL,OAAO,EACP,UAAU,EACV,eAAe,EACf,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAKrB,MAAM,YAAY,GAAG,0BAA0B,CAAC;AAChD,MAAM,YAAY,GAAG,GAAG,CAAC;AAEzB,4EAA4E;AAC5E,MAAM,iBAAiB,GAAG,MAAM,CAAC,aAAa,CAC5C,OAAO,CAAC,oBAAoB,EAC5B,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,GAAG,KAAK,EAAE,YAAY,CAAC,CACpC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,aAAa,GACjB,CAAC,QAAyB,EAAE,EAAE,CAC9B,CAAO,MAAwC,EAAE,EAAE,CACjD,MAAM,CAAC,IAAI,CACT,UAAU,CAAC,UAAU,CAAC,iBAAiB,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,EACtE,UAAU,CAAC,cAAc;AACzB,wEAAwE;AACxE,qEAAqE;AACrE,UAAU,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAC3C,UAAU,CAAC,iBAAiB,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,EACrE,UAAU,CAAC,cAAc,CAAC;IACxB,QAAQ,EAAE,QAAQ,CAAC,aAAa;IAChC,qEAAqE;IACrE,8DAA8D;IAC9D,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CACf,eAAe,CAAC,iBAAiB,CAAC,KAAK,CAAC;QACxC,KAAK,CAAC,MAAM,YAAY,eAAe,CAAC,WAAW;CACtD,CAAC,CACH,CAAC;AAEN,MAAM,cAAc,GAAG,CAAI,KAAQ,EAAE,EAAE,CACrC,eAAe,CAAC,iBAAiB,CAAC,KAAK,CAAC;IACxC,KAAK,CAAC,QAAQ,EAAE,MAAM,KAAK,YAAY,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,MAAM,gBAAgB,GACpB,CAAC,KAA8B,EAAE,EAAE,CACnC,CAAO,MAAwC,EAAE,EAAE;IACjD,MAAM,OAAO,GAAG,CAAC,OAA4C,EAAE,EAAE,CAC/D,KAAK,CAAC,GAAG,CAAC,IAAI,CACZ,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,EAAE,EAAE,CAC9B,MAAM;SACH,OAAO,CACN,iBAAiB,CAAC,SAAS,CACzB,OAAO,EACP,YAAY,EACZ,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAC7B,CACF;SACA,IAAI,CACH,iBAAiB,EACjB,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,EAAE,CAC1B,cAAc,CAAC,OAAO,CAAC;QACrB,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC;QAChC,CAAC,CAAC,MAAM,CAAC,IAAI,CAChB,CACF,CACJ,CACF,CAAC;IAEJ,OAAO,UAAU,CAAC,QAAQ,CACxB,CAAC,OAA2D,EAAE,EAAE,CAC9D,OAAO,CAAC,IAAI,CACV,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAC1B,OAAO,CAAC,QAAQ,CAAC,CAAC,IAAI,CACpB,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAClD,CACF,CACF,EACH,MAAM,CAAC,OAAO,CACf,CAAC;AACJ,CAAC,CAAC;AAEJ,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@rc312/effect-aws-imds",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Effect-native client for the AWS EC2 Instance Metadata Service (IMDSv2).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RyanCallahan312/effect-extensions.git",
+    "directory": "packages/effect-aws-imds"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "dev": "tsc -b tsconfig.json --watch",
+    "typecheck": "tsc --noEmit -p tsconfig.json --tsBuildInfoFile .cache/typecheck.tsbuildinfo && tsc -p tsconfig.test.json",
+    "test": "vitest run && node --test test/*.test.mjs",
+    "prepack": "bun run build"
+  },
+  "devDependencies": {
+    "@effect/vitest": "^4.1.2",
+    "@types/node": "^26.6.5",
+    "effect": "^4.1.2",
+    "vitest": "^5.0.4"
+  },
+  "peerDependencies": {
+    "effect": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/src/aws-imds.ts

@@ -0,0 +1,118 @@
+import { Context, Effect, flow, Layer, Schema } from "effect";
+import { HttpClient } from "effect/http";
+
+import { AwsImdsConfig } from "./config.ts";
+import { failureDetails } from "./internal.ts";
+import { AwsImdsMetadataError } from "./metadata-error.ts";
+import { AwsImdsTokenError } from "./token-error.ts";
+import { AwsImdsToken } from "./token.ts";
+import { imdsTransport, withSessionToken } from "./transport.ts";
+
+const NOT_FOUND = 404;
+
+/**
+ * Any failure produced by the IMDS services.
+ *
+ * @since 0.1.0
+ */
+type AwsImdsError = AwsImdsMetadataError | AwsImdsTokenError;
+
+const metadataError = (path: string) => (cause: Error) =>
+  new AwsImdsMetadataError({ ...failureDetails(cause), path });
+
+// Token failures surface as themselves; everything else is about `path`.
+const toImdsError = (path: string) => (cause: Error) =>
+  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<
+  AwsImds,
+  {
+    readonly get: (path: string) => Effect.Effect<string, AwsImdsError>;
+  }
+>()("@rc312/effect-aws-imds/AwsImds") {
+  /** Reads through the `HttpClient` with tokens from `AwsImdsToken`. */
+  static readonly layer: Layer.Layer<
+    AwsImds,
+    never,
+    AwsImdsToken | HttpClient.HttpClient
+  > = 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 = <A, RD>(path: string, codec: Schema.Codec<A, string, RD>) =>
+  flow(
+    (text: string) => Schema.decodeEffect(codec)(text),
+    Effect.mapError(metadataError(path))
+  );
+
+/**
+ * Reads the raw text at a metadata path.
+ *
+ * @since 0.1.0
+ */
+const get = (path: string) => 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 = <A, RD>(path: string, codec: Schema.Codec<A, string, RD>) =>
+  get(path).pipe(Effect.flatMap(decodeAt(path, codec)));
+
+const isNotFound = <E>(error: E) =>
+  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 = <A, E, R>(self: Effect.Effect<A, E, R>) =>
+  self.pipe(
+    Effect.asSome,
+    Effect.catchIf(isNotFound, () => Effect.succeedNone)
+  );
+
+export { AwsImds, decodeAt, get, getSchema, optional };
+
+export type { AwsImdsError };