ListenOptionsShared options for unix / http / ws (and low-level *Server) —
rpc path / health / ipc unlink, plus optional fixed listen address for nameless Http/Ws.
export type type ListenOptions = {
readonly path?: HttpRouter.PathInput
readonly serialization?: Layer.Layer<RpcSerialization.RpcSerialization>
readonly health?: {
readonly path?: HttpRouter.PathInput
}
readonly node?:
| string
| {
readonly key: string
}
readonly unlink?: boolean
readonly onConflict?: OnConflict
readonly port?: number
readonly url?: string
readonly assumeToken?:
| string
| Redacted.Redacted<string>
readonly onYield?: Effect.Effect<boolean>
}
Shared options for
unix
/
http
/
ws
(and low-level *Server) —
rpc path / health / ipc unlink, plus optional fixed listen address for nameless Http/Ws.
ListenOptions = {
readonly path?: HttpRouter.PathInput | undefinedpath?: import HttpRouterHttpRouter.type PathInput = `/${string}` | "*"Path pattern accepted by the router. Routes must use an absolute path
beginning with / or the wildcard *.
PathInput;
readonly serialization?: Layer.Layer<RpcSerialization.RpcSerialization>serialization?: import LayerLayer.interface Layer<in ROut, out E = never, out RIn = never>A Layer describes how to build one or more services for dependency injection.
When to use
Use to model construction of application services for dependency injection,
especially when services have dependencies, can fail during construction, or
need scoped setup and release.
Details
A Layer<ROut, E, RIn> represents ROut as the services this layer
provides, E as the possible errors during layer construction, and RIn as
the services this layer requires as dependencies.
Layer<import RpcSerializationRpcSerialization.class RpcSerializationclass RpcSerialization {
key: Identifier;
Service: {
makeUnsafe: () => RpcSerialization.Parser;
contentType: string;
includesFraming: boolean;
};
}
Service that describes how RPC protocol messages are encoded and decoded,
including the content type and whether the serialization format provides
message framing.
When to use
Use to provide the serialization boundary shared by RPC clients and servers
for a chosen wire format.
RpcSerialization>;
readonly health?: | {
readonly path?: HttpRouter.PathInput
}
| undefined
path?: HttpRouter.PathInput | undefinedpath?: import HttpRouterHttpRouter.type PathInput = `/${string}` | "*"Path pattern accepted by the router. Routes must use an absolute path
beginning with / or the wildcard *.
PathInput };
readonly node?: | string
| {
readonly key: string
}
| undefined
key: stringkey: string };
readonly unlink?: boolean | undefinedunlink?: boolean;
/**
* Directory advertise conflict policy for this listen (call-site; wins over node stamp).
* Omit / `"inherit"` → continue resolve chain.
*/
readonly onConflict?: OnConflictDirectory advertise conflict policy for this listen (call-site; wins over node stamp).
Omit / "inherit" → continue resolve chain.
onConflict?: type OnConflict =
| "livenessReplace"
| "askIncumbent"
| "reject"
| "inherit"
Directory advertise conflict policy when the same nodeKey already has a row.
livenessReplace — ping incumbent; alive → reject; dead → replaceaskIncumbent — if alive, Lookup asks the incumbent node-status yield; refuse/timeout → rejectreject — alive → reject; dead → still replaceinherit — continue up the resolve chain (call-site → node → Lookup → hard fallback)
OnConflict;
/**
* Fixed listen address for nameless / address-less {@link http} / {@link ws}.
* `port` is loopback shorthand (`http://127.0.0.1:<port>/rpc` or `ws://…`).
* `url` wins when both are set; battery bind still requires a loopback url (non-loopback
* → use {@link httpServer} / {@link wsServer} + your platform layer).
* Omit both for an ephemeral loopback port (`port: 0`).
*/
readonly port?: number | undefinedFixed listen address for nameless / address-less
http
/
ws
.
port is loopback shorthand (http://127.0.0.1:<port>/rpc or ws://…).
url wins when both are set; battery bind still requires a loopback url (non-loopback
→ use
httpServer
/
wsServer
- your platform layer).
Omit both for an ephemeral loopback port (
port: 0).
port?: number;
readonly url?: string | undefinedurl?: string;
/**
* Expected launcher ownership-ack token for {@link Node.assume}. When set, node status
* mirrors `ownership: "launcher" | "self"`. Injection into the child is open (env / argv /
* {@link Config}); this option only arms the handshake on the listening node.
*/
readonly assumeToken?: string | Redacted.Redacted<string>Expected launcher ownership-ack token for
Node.assume
. When set, node status
mirrors ownership: "launcher" | "self". Injection into the child is open (env / argv /
Config
); this option only arms the handshake on the listening node.
assumeToken?: string | import RedactedRedacted.interface Redacted<out A = string>A wrapper for sensitive values whose string, JSON, and inspection output is
redacted.
When to use
Use to carry sensitive values while reducing accidental exposure in string,
JSON, and inspection output.
Gotchas
The underlying value is still stored in memory and can be recovered with
Redacted.value until the wrapper is wiped or becomes unreachable. Use
Redacted to reduce accidental disclosure in logs and diagnostics, not as a
cryptographic protection mechanism.
Example (Creating redacted values)
import { Redacted } from "effect"
// Create a redacted value to protect sensitive information
const apiKey = Redacted.make("secret-key")
const userPassword = Redacted.make("user-password")
// TypeScript will infer the types as Redacted<string>
Namespace containing type-level members associated with Redacted values.
When to use
Use to access type-level helpers associated with Redacted.
Example (Using namespace utilities)
import { Redacted } from "effect"
// Use the Redacted namespace for type-level operations
const secret = Redacted.make("my-secret")
// The namespace contains utilities for working with Redacted values
const isRedacted = Redacted.isRedacted(secret) // true
Redacted<string>;
/**
* Cooperative directory handoff handler for Lookup {@link OnConflict} `"askIncumbent"` —
* wired to the auto-mounted node-status `yield` RPC. `true` = step aside (row may replace);
* `false` / timeout → newcomer sees Lookup `IncumbentAlive`. Default when omitted: accept.
* Does **not** drain work or shut down the process (Track C).
*/
readonly onYield?: Effect.Effect<boolean>Cooperative directory handoff handler for Lookup
OnConflict
"askIncumbent" —
wired to the auto-mounted node-status yield RPC. true = step aside (row may replace);
false / timeout → newcomer sees Lookup IncumbentAlive. Default when omitted: accept.
Does not drain work or shut down the process (Track C).
onYield?: import EffectEffect.interface Effect<out A, out E = never, out R = never>The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Effect<boolean>;
};