Credentials

Credentials are Redacted values, never plain strings. Pass a fixed value for a static password, or an Effect that fetches one when a connection opens.

Using a fixed passwordCopy Anchor Link

Put the secret in a Redacted and read it from Config, so it never appears in logs.

Example (Reading a Password from the Environment)

import { Config } from "effect";
import { RedisNode } from "@effect-kit/redis/node";

export const RedisLive = RedisNode.layerConfig(
  Config.all({
    url: Config.String("REDIS_URL"),
    credentials: Config.all({
      username: Config.Redacted("REDIS_USERNAME"),
      password: Config.Redacted("REDIS_PASSWORD"),
    }),
  }),
);

username is optional. A password in the URL (rediss://user:pass@host) also works, but giving both a URL password and credentials fails with RedisConfigError. A plain string for credentials is a type error.

Fetching credentials on demandCopy Anchor Link

Pass an Effect that returns the values. It runs for every new connection, and may require services, which become requirements of the layer.

Example (A Token Source That the Layer Requires)

import { Context, Effect } from "effect";
import type { Layer } from "effect";
import { RedisCredentials } from "@effect-kit/redis";
import type { CredentialValues } from "@effect-kit/redis";
import { RedisNode } from "@effect-kit/redis/node";

class TokenSource extends Context.Service<
  TokenSource,
  { readonly next: Effect.Effect<CredentialValues> }
>()("app/TokenSource") {}

const acquire = Effect.gen(function* () {
  const source = yield* TokenSource;
  return yield* source.next;
});

export const RedisLive = RedisNode.layer({
  url: "rediss://cache.example.com:6380",
  credentials: RedisCredentials.provider(acquire, { refreshBeforeMillis: 120_000 }),
});

type Needs = Layer.Services<typeof RedisLive>;
     
type Needs = TokenSource

RedisCredentials.provider(effect, policy) wraps the effect with a cache. The values it returns have password, optional username, and optional expiresAtMillis: an absolute UTC time in epoch milliseconds, as a number.

An Effect passed directly as credentials is the same as RedisCredentials.provider(effect) with these defaults. If the effect fails or times out, opening the connection fails with HandshakeError where stage is "credentials".

Retiring connections before a token expiresCopy Anchor Link

A connection authenticates once, when it opens. credentialLifetime decides when an open connection is closed so the next command reopens it with fresh credentials.

Example (Closing Connections Before the Token Expires)

import { Effect, Redacted } from "effect";
import { RedisCredentials } from "@effect-kit/redis";
import { RedisNode } from "@effect-kit/redis/node";

const fetchToken = Effect.sync(() => ({
  username: Redacted.make("app"),
  password: Redacted.make("short-lived-token"),
  expiresAtMillis: Date.now() + 15 * 60 * 1000,
}));

export const RedisLive = RedisNode.layer({
  url: "rediss://cache.example.com:6380",
  credentials: RedisCredentials.provider(fetchToken),
  credentialLifetime: { mode: "token-expiry", retireBeforeMillis: 30_000 },
});

The package does not insert AUTH into an open connection. It closes the connection and lets the next one authenticate. A cached token is also refreshed at least retireBeforeMillis early in this mode.

Rotating on demandCopy Anchor Link

RedisCredentials is a service the runtime layer provides. Its rotate effect discards the cached credentials and closes the open connections. New connections fetch fresh credentials.

Example (Rotating After a Secret Changes)

import { Effect } from "effect";
import { RedisCredentials } from "@effect-kit/redis";

export const rotate = Effect.gen(function* () {
  const credentials = yield* RedisCredentials;
  yield* credentials.rotate;
});

On Upstash, rotate aborts in-flight HTTP requests instead of closing connections. rotate fails with CredentialError, whose reason is one of configuration, acquisition, expired, timeout, capacity, closed, rotated or retirement.

Credential errors never include the secret or the provider response.