effect-vercel 0.1.0

package/src/VercelOidc.ts

@@ -0,0 +1,86 @@
+/**
+ * The OIDC token Vercel issues to a deployment.
+ *
+ * In Functions the token arrives on each request as the `x-vercel-oidc-token`
+ * header and rotates, so it is read on every run of `token`/`find`, never
+ * cached. In builds and after `vercel env pull` it is `VERCEL_OIDC_TOKEN`.
+ * Use it to authenticate to the AI Gateway, or exchange it for cloud
+ * credentials (AWS `AssumeRoleWithWebIdentity`, GCP workload identity
+ * federation).
+ *
+ * @example
+ * ```ts
+ * import { VercelOidc } from "effect-vercel/oidc"
+ * import { Effect, Redacted } from "effect"
+ *
+ * const program = Effect.gen(function* () {
+ *   const token = yield* VercelOidc.token
+ *   // pass Redacted.value(token) as the web identity token
+ * })
+ * ```
+ */
+
+import { Config, Data, Effect, Option, Redacted } from "effect"
+
+/** The environment variable read when no request carries a token. */
+export const TOKEN_ENV = "VERCEL_OIDC_TOKEN"
+
+/** No usable OIDC token. */
+export class VercelOidcError extends Data.TaggedError("VercelOidcError")<{
+  readonly message: string
+  readonly hints: ReadonlyArray<string>
+  readonly cause?: unknown
+}> {}
+
+/** How to make a token available. */
+export const hints: ReadonlyArray<string> = [
+  "Run on Vercel, where each request carries an OIDC token.",
+  `Or run \`vercel env pull\` locally to populate ${TOKEN_ENV}.`,
+]
+
+/**
+ * Vercel exposes the current request's context on a well-known global symbol.
+ * In Functions, the `x-vercel-oidc-token` header of the request lives there.
+ * Mirrors `@vercel/oidc`'s `getVercelOidcTokenSync`, minus the dev-time
+ * refresh that package also offers.
+ */
+const REQUEST_CONTEXT = Symbol.for("@vercel/request-context")
+
+type RequestContext = { readonly headers?: Record<string, string | undefined> }
+
+const fromRequestContext = Effect.sync(() => {
+  const holder = globalThis as typeof globalThis & {
+    [REQUEST_CONTEXT]?: { get?: () => RequestContext | undefined }
+  }
+  return Option.fromNullishOr(
+    holder[REQUEST_CONTEXT]?.get?.()?.headers?.["x-vercel-oidc-token"],
+  ).pipe(Option.map(Redacted.make))
+})
+
+const fromEnv = Config.option(Config.redacted(TOKEN_ENV)).pipe(
+  Effect.catchTag(
+    "ConfigError",
+    (cause) => new VercelOidcError({ message: `Failed to read ${TOKEN_ENV}.`, hints, cause }),
+  ),
+)
+
+/**
+ * The token if one is available: the request header, else `VERCEL_OIDC_TOKEN`.
+ * `None` means neither is set, so a caller can fall back to something else.
+ */
+export const find: Effect.Effect<
+  Option.Option<Redacted.Redacted<string>>,
+  VercelOidcError
+> = Effect.flatMap(fromRequestContext, (found) =>
+  Option.isSome(found) ? Effect.succeed(found) : fromEnv,
+)
+
+/** Like `find`, but fails when no token is available. */
+export const token: Effect.Effect<Redacted.Redacted<string>, VercelOidcError> = Effect.flatMap(
+  find,
+  Option.match({
+    onNone: () =>
+      Effect.fail(new VercelOidcError({ message: "No Vercel OIDC token is available.", hints })),
+    onSome: Effect.succeed,
+  }),
+)

package/src/VercelRuntimeCache.ts

@@ -0,0 +1,108 @@
+/**
+ * Effect `Persistence` backed by the Vercel Runtime Cache, so a
+ * `PersistedCache` shares results across Function instances in a region.
+ *
+ * Outside Vercel, `getCache` falls back to an in-memory cache, so the same
+ * layer works in local dev and tests.
+ *
+ * @example
+ * ```ts
+ * import { VercelRuntimeCache } from "effect-vercel/runtime-cache"
+ * import { Effect } from "effect"
+ * import { PersistedCache } from "effect/unstable/persistence"
+ *
+ * const program = Effect.gen(function* () {
+ *   const users = yield* PersistedCache.make(fetchUser, {
+ *     storeId: "users",
+ *     timeToLive: () => "1 hour",
+ *   })
+ *   return yield* users.get(new GetUser({ id: 1 }))
+ * }).pipe(Effect.scoped, Effect.provide(VercelRuntimeCache.layer))
+ * ```
+ */
+
+import { createHash } from "node:crypto"
+import { getCache, type RuntimeCache } from "@vercel/functions"
+import { Duration, Effect, Layer } from "effect"
+import { Persistence } from "effect/unstable/persistence"
+
+const sha256 = (key: string) => createHash("sha256").update(key).digest("hex")
+
+/**
+ * A `BackingPersistence` over `cache`.
+ *
+ * Entries are keyed by the JSON pair `[storeId, key]`, so no two stores share
+ * a key. Each entry is tagged with a hash of the store id, since tags are
+ * joined with `,` and sent unescaped, and `clear` expires that tag. Entries
+ * are sent without a name, so keys don't reach Vercel's o11y or the request
+ * headers, where non-Latin-1 characters would make the write fail. TTLs round
+ * up to whole seconds, the cache's resolution.
+ *
+ * `getCache()` hashes keys with a 32-bit hash by default, which can collide.
+ * Pass a cache made with a stronger `keyHashFunction`, as `layerBacking` does.
+ */
+export const makeBacking = (cache: RuntimeCache): Persistence.BackingPersistence["Service"] =>
+  Persistence.BackingPersistence.of({
+    make: (storeId) =>
+      Effect.sync(() => {
+        const prefixed = (key: string) => JSON.stringify([storeId, key])
+        const tag = `effect-persistence:${sha256(storeId)}`
+
+        const get = (key: string) =>
+          Effect.tryPromise({
+            try: () => cache.get(prefixed(key)),
+            catch: (cause) =>
+              new Persistence.PersistenceError({ message: `Failed to get key ${key}`, cause }),
+          }).pipe(
+            Effect.map((value) =>
+              typeof value === "object" && value !== null ? value : undefined,
+            ),
+          )
+
+        const set = (key: string, value: object, ttl: Duration.Duration | undefined) =>
+          Effect.tryPromise({
+            try: () =>
+              cache.set(prefixed(key), value, {
+                name: "",
+                tags: [tag],
+                ...(ttl && { ttl: Math.max(1, Math.ceil(Duration.toSeconds(ttl))) }),
+              }),
+            catch: (cause) =>
+              new Persistence.PersistenceError({ message: `Failed to set key ${key}`, cause }),
+          })
+
+        return {
+          get,
+          getMany: (keys) => Effect.forEach(keys, get, { concurrency: "unbounded" }),
+          set,
+          // Writes run concurrently, so keep only the last entry for each key.
+          setMany: (entries) =>
+            Effect.forEach(
+              new Map(entries.map(([key, value, ttl]) => [key, [value, ttl] as const])),
+              ([key, [value, ttl]]) => set(key, value, ttl),
+              { concurrency: "unbounded", discard: true },
+            ),
+          remove: (key) =>
+            Effect.tryPromise({
+              try: () => cache.delete(prefixed(key)),
+              catch: (cause) =>
+                new Persistence.PersistenceError({ message: `Failed to remove key ${key}`, cause }),
+            }),
+          clear: Effect.tryPromise({
+            try: () => cache.expireTag(tag),
+            catch: (cause) =>
+              new Persistence.PersistenceError({ message: `Failed to clear ${storeId}`, cause }),
+          }),
+        }
+      }),
+  })
+
+/** `BackingPersistence` over `getCache()`, with SHA-256 key hashing. */
+export const layerBacking: Layer.Layer<Persistence.BackingPersistence> = Layer.sync(
+  Persistence.BackingPersistence,
+)(() => makeBacking(getCache({ keyHashFunction: sha256 })))
+
+/** `Persistence` backed by the Vercel Runtime Cache. */
+export const layer: Layer.Layer<Persistence.Persistence> = Persistence.layer.pipe(
+  Layer.provide(layerBacking),
+)

package/src/ai-gateway.ts

@@ -0,0 +1,2 @@
+export * as AiGateway from "./AiGateway.js"
+export * as AiGatewayCredentials from "./AiGatewayCredentials.js"

package/src/oidc.ts

@@ -0,0 +1 @@
+export * as VercelOidc from "./VercelOidc.js"

package/src/runtime-cache.ts

@@ -0,0 +1 @@
+export * as VercelRuntimeCache from "./VercelRuntimeCache.js"