@wmaurer/effect-ai-amazon-bedrock 0.1.0 → 0.3.0

package/src/AmazonBedrockClient.ts

@@ -13,9 +13,8 @@
  * `converse-stream` (streaming) endpoints.
  *
  * @stability unstable
- * @since 4.0.0
+ * @since 0.1.0
  */
-import { AwsV4Signer } from "aws4fetch"
 import type * as AiError from "effect/ai/AiError"
 import * as Array from "effect/Array"
 import type * as Config from "effect/Config"
@@ -28,13 +27,13 @@ import * as HttpClient from "effect/http/HttpClient"
 import * as HttpClientRequest from "effect/http/HttpClientRequest"
 import * as HttpClientResponse from "effect/http/HttpClientResponse"
 import * as Layer from "effect/Layer"
-import * as Predicate from "effect/Predicate"
-import * as Redacted from "effect/Redacted"
+import type * as Redacted from "effect/Redacted"
 import * as Stream from "effect/Stream"
 import { AmazonBedrockConfig } from "./AmazonBedrockConfig.ts"
 import * as EventStream from "./AmazonBedrockEventStream.ts"
 import type { ConverseRequest } from "./AmazonBedrockSchema.ts"
 import { ConverseResponse, ConverseResponseStreamEvent } from "./AmazonBedrockSchema.ts"
+import * as Authentication from "./internal/credentials.ts"
 import * as Errors from "./internal/errors.ts"
 
 // =============================================================================
@@ -47,7 +46,7 @@ import * as Errors from "./internal/errors.ts"
  *
  * @stability unstable
  * @category models
- * @since 4.0.0
+ * @since 0.1.0
  */
 export interface Service {
   /**
@@ -76,7 +75,7 @@ export interface Service {
  *
  * @stability unstable
  * @category services
- * @since 4.0.0
+ * @since 0.1.0
  */
 export class AmazonBedrockClient extends Context.Service<AmazonBedrockClient, Service>()(
   "@wmaurer/effect-ai-amazon-bedrock/AmazonBedrockClient"
@@ -87,13 +86,58 @@ export class AmazonBedrockClient extends Context.Service<AmazonBedrockClient, Se
 // =============================================================================
 
 /**
- * Configuration for creating an Amazon Bedrock client.
+ * SigV4 credentials as a {@link CredentialProvider} returns them. The shape is
+ * the AWS SDK's `AwsCredentialIdentity`, so the SDK's providers fit without an
+ * adapter.
  *
  * @stability unstable
  * @category options
- * @since 4.0.0
+ * @since 0.2.0
  */
-export type Options = {
+export interface Credentials {
+  readonly accessKeyId: string
+  readonly secretAccessKey: string
+  /** An empty token is sent as no token. */
+  readonly sessionToken?: string | undefined
+  /** The client asks the provider for new credentials five minutes before this time. */
+  readonly expiration?: Date | undefined
+}
+
+/**
+ * Supplies SigV4 credentials that can change while the program runs.
+ *
+ * **Details**
+ *
+ * A provider is one of these:
+ *
+ * - A function in the shape of the AWS SDK's credential providers, such as
+ *   `fromNodeProviderChain()` from `@aws-sdk/credential-providers`. A rejected
+ *   promise fails the request with an `AuthenticationError` of kind
+ *   `"Unknown"`. After Bedrock rejects the credentials, the client calls the
+ *   function with `{ forceRefresh: true }`.
+ * - An `Effect`. It can fail with an `AiError`, which the request fails with
+ *   unchanged, or with an `AiError` reason, such as an `AuthenticationError`,
+ *   which the client wraps in an `AiError`. The services that it requires
+ *   become requirements of the layer. It runs with the services of the
+ *   request first, and the services that the layer was built with fill in the
+ *   rest.
+ *
+ * The client runs the provider at most once at a time, and keeps the
+ * credentials until five minutes before their `expiration`. Credentials with
+ * no `expiration` are kept until Bedrock rejects them. Keys that are empty fail
+ * the request with an `AuthenticationError` of kind `"MissingKey"`.
+ *
+ * @stability unstable
+ * @category options
+ * @since 0.2.0
+ */
+export type CredentialProvider<R = never> =
+  // `forceRefresh` has no `| undefined`: with `exactOptionalPropertyTypes`, the
+  // AWS SDK's provider types would not assign to it.
+  | ((options?: { readonly forceRefresh?: boolean }) => PromiseLike<Credentials>)
+  | Effect.Effect<Credentials, AiError.AiError | AiError.AiErrorReason, R>
+
+interface CommonOptions {
   /**
    * The base URL for the Bedrock runtime API. Override to use a proxy or a
    * different endpoint.
@@ -101,9 +145,6 @@ export type Options = {
    * @default `https://bedrock-runtime.${region}.amazonaws.com`
    */
   readonly apiUrl?: string | undefined
-  readonly accessKeyId: string
-  readonly secretAccessKey: Redacted.Redacted<string>
-  readonly sessionToken?: Redacted.Redacted<string> | undefined
   /**
    * The AWS region.
    *
@@ -113,6 +154,81 @@ export type Options = {
   readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
 }
 
+interface StaticKeys {
+  readonly accessKeyId: string
+  readonly secretAccessKey: Redacted.Redacted<string>
+  readonly sessionToken?: Redacted.Redacted<string> | undefined
+  readonly credentialProvider?: never
+  readonly apiKey?: never
+}
+
+interface ProvidedKeys<R> {
+  readonly credentialProvider: CredentialProvider<R>
+  readonly accessKeyId?: never
+  readonly secretAccessKey?: never
+  readonly sessionToken?: never
+  readonly apiKey?: never
+}
+
+interface ApiKey {
+  /** A Bedrock API key, sent as `Authorization: Bearer <key>` in place of a SigV4 signature. */
+  readonly apiKey: Redacted.Redacted<string>
+  readonly accessKeyId?: never
+  readonly secretAccessKey?: never
+  readonly sessionToken?: never
+  readonly credentialProvider?: never
+}
+
+/**
+ * Configuration for creating an Amazon Bedrock client.
+ *
+ * **Details**
+ *
+ * The options take exactly one way to authenticate:
+ *
+ * - `accessKeyId` and `secretAccessKey`, and an optional `sessionToken`.
+ * - `credentialProvider`, a {@link CredentialProvider}.
+ * - `apiKey`, a Bedrock API key.
+ *
+ * @stability unstable
+ * @category options
+ * @since 0.1.0
+ */
+export type Options<R = never> = CommonOptions & (StaticKeys | ProvidedKeys<R> | ApiKey)
+
+/**
+ * The {@link Options} of {@link layerConfig}, with a `Config` for each value.
+ * `credentialProvider` and `transformClient` are not configuration, so they
+ * take the same values as in {@link Options}.
+ *
+ * @stability unstable
+ * @category options
+ * @since 0.2.0
+ */
+export type ConfigOptions<R = never> =
+  & {
+    readonly apiUrl?: Config.Config<string> | undefined
+    readonly region?: Config.Config<string> | undefined
+    readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
+  }
+  & (
+    | {
+      readonly accessKeyId: Config.Config<string>
+      readonly secretAccessKey: Config.Config<Redacted.Redacted<string>>
+      readonly sessionToken?: Config.Config<Redacted.Redacted<string>> | undefined
+      readonly credentialProvider?: never
+      readonly apiKey?: never
+    }
+    | ProvidedKeys<R>
+    | {
+      readonly apiKey: Config.Config<Redacted.Redacted<string>>
+      readonly accessKeyId?: never
+      readonly secretAccessKey?: never
+      readonly sessionToken?: never
+      readonly credentialProvider?: never
+    }
+  )
+
 // =============================================================================
 // Constructor
 // =============================================================================
@@ -130,11 +246,19 @@ const withRedactedHeaders = Effect.updateService(Headers.CurrentRedactedNames, a
  *
  * @stability unstable
  * @category constructors
- * @since 4.0.0
+ * @since 0.1.0
  */
-export const make = Effect.fnUntraced(
-  function*(options: Options): Effect.fn.Return<Service, never, HttpClient.HttpClient> {
+export const make = <R = never>(options: Options<R>): Effect.Effect<Service, never, HttpClient.HttpClient | R> =>
+  makeUnsafe(options)
+
+// Takes each authentication field as optional, as `layerConfig` reads them.
+// `Authentication.make` dies on a mix of the ways to authenticate.
+const makeUnsafe = <R>(
+  options: CommonOptions & Authentication.AuthenticationOptions<R>
+): Effect.Effect<Service, never, HttpClient.HttpClient | R> =>
+  Effect.gen(function*() {
     const region = options.region ?? "us-east-1"
+    const authenticator = yield* Authentication.make(options)
 
     const baseClient = yield* HttpClient.HttpClient
 
@@ -145,23 +269,7 @@ export const make = Effect.fnUntraced(
           HttpClientRequest.acceptJson
         )
       ),
-      HttpClient.mapRequestEffect(Effect.fnUntraced(function*(request) {
-        const originalHeaders = request.headers
-        const signer = new AwsV4Signer({
-          service: "bedrock",
-          url: request.url,
-          method: request.method,
-          headers: Object.entries(originalHeaders),
-          body: prepareBody(request.body),
-          region,
-          accessKeyId: options.accessKeyId,
-          secretAccessKey: Redacted.value(options.secretAccessKey),
-          ...(options.sessionToken ? { sessionToken: Redacted.value(options.sessionToken) } : {})
-        })
-        const { headers: signedHeaders } = yield* Effect.promise(() => signer.sign())
-        const headers = Headers.merge(originalHeaders, Headers.fromInput(signedHeaders))
-        return HttpClientRequest.setHeaders(request, headers)
-      })),
+      HttpClient.mapRequestEffect(Authentication.authenticateRequest(region)),
       options.transformClient ? options.transformClient : identity
     )
 
@@ -172,15 +280,24 @@ export const make = Effect.fnUntraced(
       return config?.transformClient ? config.transformClient(httpClientOk) : httpClientOk
     })
 
+    const resolveCredentials = (method: string) =>
+      Effect.mapError(authenticator.resolve, Errors.mapCredentialProviderError(method))
+
     const converse: Service["converse"] = ({ payload: { modelId, ...body } }) =>
-      Effect.flatMap(withConfigClient(), (client) => {
+      Effect.gen(function*() {
+        const client = yield* withConfigClient()
+        const credentials = yield* resolveCredentials("converse")
         const request = HttpClientRequest.post(`/model/${modelId}/converse`, {
           body: HttpBody.jsonUnsafe(body)
         })
-        return client.execute(request).pipe(
+        return yield* client.execute(request).pipe(
+          Effect.provideService(Authentication.CurrentRequestCredentials, credentials),
           Effect.flatMap(HttpClientResponse.schemaBodyJson(ConverseResponse)),
           Effect.catchTags({
-            HttpClientError: (error) => Errors.mapHttpClientError(error, "converse"),
+            HttpClientError: (error) =>
+              Errors.mapHttpClientError(error, "converse").pipe(
+                Effect.tapError(Authentication.invalidateIfRejected(authenticator, credentials))
+              ),
             SchemaError: (error) => Effect.fail(Errors.mapSchemaError(error, "converse"))
           }),
           withRedactedHeaders
@@ -192,18 +309,27 @@ export const make = Effect.fnUntraced(
         body: HttpBody.jsonUnsafe(body)
       })
       return Stream.unwrap(
-        Effect.map(withConfigClient(), (client) =>
-          client.execute(request).pipe(
+        Effect.gen(function*() {
+          const client = yield* withConfigClient()
+          const credentials = yield* resolveCredentials("converseStream")
+          return client.execute(request).pipe(
+            Effect.provideService(Authentication.CurrentRequestCredentials, credentials),
             Effect.map((response) => response.stream),
             Stream.unwrap,
             Stream.pipeThroughChannel(EventStream.makeChannel(ConverseResponseStreamEvent)),
             Stream.catchTags({
-              HttpClientError: (error) => Stream.fromEffect(Errors.mapHttpClientError(error, "converseStream")),
+              HttpClientError: (error) =>
+                Stream.fromEffect(
+                  Errors.mapHttpClientError(error, "converseStream").pipe(
+                    Effect.tapError(Authentication.invalidateIfRejected(authenticator, credentials))
+                  )
+                ),
               SchemaError: (error) => Stream.fail(Errors.mapSchemaError(error, "converseStream")),
               EventStreamError: (error) => Stream.fail(Errors.mapEventStreamError(error, "converseStream"))
             }),
             Stream.updateService(Headers.CurrentRedactedNames, appendRedactedHeaders)
-          ))
+          )
+        })
       )
     }
 
@@ -211,9 +337,7 @@ export const make = Effect.fnUntraced(
       converse,
       converseStream
     })
-  },
-  withRedactedHeaders
-)
+  }).pipe(withRedactedHeaders)
 
 // =============================================================================
 // Layers
@@ -224,9 +348,11 @@ export const make = Effect.fnUntraced(
  *
  * @stability unstable
  * @category layers
- * @since 4.0.0
+ * @since 0.1.0
  */
-export const layer = (options: Options): Layer.Layer<AmazonBedrockClient, never, HttpClient.HttpClient> =>
+export const layer = <R = never>(
+  options: Options<R>
+): Layer.Layer<AmazonBedrockClient, never, HttpClient.HttpClient | R> =>
   Layer.effect(AmazonBedrockClient, make(options))
 
 /**
@@ -235,63 +361,26 @@ export const layer = (options: Options): Layer.Layer<AmazonBedrockClient, never,
  *
  * @stability unstable
  * @category layers
- * @since 4.0.0
+ * @since 0.1.0
  */
-export const layerConfig = (options: {
-  readonly apiUrl?: Config.Config<string> | undefined
-  readonly accessKeyId: Config.Config<string>
-  readonly secretAccessKey: Config.Config<Redacted.Redacted<string>>
-  readonly sessionToken?: Config.Config<Redacted.Redacted<string>> | undefined
-  readonly region?: Config.Config<string> | undefined
-  readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient) | undefined
-}): Layer.Layer<AmazonBedrockClient, Config.ConfigError, HttpClient.HttpClient> =>
+export const layerConfig = <R = never>(
+  options: ConfigOptions<R>
+): Layer.Layer<AmazonBedrockClient, Config.ConfigError, HttpClient.HttpClient | R> =>
   Layer.effect(
     AmazonBedrockClient,
     Effect.gen(function*() {
-      const apiUrl = Predicate.isNotUndefined(options.apiUrl)
-        ? yield* options.apiUrl :
-        undefined
-      const accessKeyId = yield* options.accessKeyId
-      const secretAccessKey = yield* options.secretAccessKey
-      const sessionToken = Predicate.isNotUndefined(options.sessionToken)
-        ? yield* options.sessionToken :
-        undefined
-      const region = Predicate.isNotUndefined(options.region)
-        ? yield* options.region :
-        undefined
-      return yield* make({
-        apiUrl,
-        accessKeyId,
-        secretAccessKey,
-        sessionToken,
-        region,
+      return yield* makeUnsafe({
+        apiUrl: yield* readOptional(options.apiUrl),
+        region: yield* readOptional(options.region),
+        accessKeyId: yield* readOptional(options.accessKeyId),
+        secretAccessKey: yield* readOptional(options.secretAccessKey),
+        sessionToken: yield* readOptional(options.sessionToken),
+        apiKey: yield* readOptional(options.apiKey),
+        credentialProvider: options.credentialProvider,
         transformClient: options.transformClient
       })
     })
   )
 
-// =============================================================================
-// Utilities
-// =============================================================================
-
-const prepareBody = (body: HttpBody.HttpBody): string => {
-  switch (body._tag) {
-    case "Empty": {
-      return ""
-    }
-    case "Raw":
-    case "Uint8Array": {
-      if (typeof body.body === "string") {
-        return body.body
-      }
-      if (body.body instanceof Uint8Array) {
-        return new TextDecoder().decode(body.body)
-      }
-      if (body.body instanceof ArrayBuffer) {
-        return new TextDecoder().decode(body.body)
-      }
-      return JSON.stringify(body.body)
-    }
-  }
-  throw new Error("Unsupported HttpBody: " + body._tag)
-}
+const readOptional = <A>(config: Config.Config<A> | undefined): Effect.Effect<A | undefined, Config.ConfigError> =>
+  config === undefined ? Effect.undefined : config

package/src/AmazonBedrockConfig.ts

@@ -4,7 +4,7 @@
  * underlying HTTP client without changing individual request code.
  *
  * @stability unstable
- * @since 4.0.0
+ * @since 0.1.0
  */
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
@@ -17,7 +17,7 @@ import type { HttpClient } from "effect/http/HttpClient"
  *
  * @stability unstable
  * @category services
- * @since 4.0.0
+ * @since 0.1.0
  */
 export class AmazonBedrockConfig extends Context.Service<
   AmazonBedrockConfig,
@@ -26,7 +26,7 @@ export class AmazonBedrockConfig extends Context.Service<
   /**
    * Gets the configured Amazon Bedrock service from the current context when present.
    *
-   * @since 4.0.0
+   * @since 0.1.0
    */
   static readonly getOrUndefined: Effect.Effect<typeof AmazonBedrockConfig.Service | undefined> = Effect.map(
     Effect.context<never>(),
@@ -38,14 +38,14 @@ export class AmazonBedrockConfig extends Context.Service<
  * Namespace containing types associated with the `AmazonBedrockConfig` service.
  *
  * @stability unstable
- * @since 4.0.0
+ * @since 0.1.0
  */
 export declare namespace AmazonBedrockConfig {
   /**
    * Configuration provided through `AmazonBedrockConfig`.
    *
    * @category models
-   * @since 4.0.0
+   * @since 0.1.0
    */
   export interface Service {
     readonly transformClient?: ((client: HttpClient) => HttpClient) | undefined
@@ -58,7 +58,7 @@ export declare namespace AmazonBedrockConfig {
  *
  * @stability unstable
  * @category configuration
- * @since 4.0.0
+ * @since 0.1.0
  */
 export const withClientTransform: {
   (transform: (client: HttpClient) => HttpClient): <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>

package/src/AmazonBedrockEventStream.ts

@@ -17,7 +17,7 @@
  * for more information.
  *
  * @stability unstable
- * @since 4.0.0
+ * @since 0.1.0
  */
 import * as Arr from "effect/Array"
 import type { NonEmptyReadonlyArray } from "effect/Array"
@@ -35,7 +35,7 @@ const textDecoder = new TextDecoder()
  *
  * @stability unstable
  * @category errors
- * @since 4.0.0
+ * @since 0.1.0
  */
 export class EventStreamError extends Schema.TaggedError<EventStreamError>(
   "@wmaurer/effect-ai-amazon-bedrock/AmazonBedrockEventStream/EventStreamError"
@@ -138,7 +138,7 @@ const decodeFrame = (frame: Uint8Array): DecodedFrame => {
  *
  * @stability unstable
  * @category constructors
- * @since 4.0.0
+ * @since 0.1.0
  */
 export const makeChannel = <A, I, RD, IE, Done>(
   schema: Schema.Codec<A, I, RD>