Sharding and Supervision

fileSessionStore#

fileSessionStore(directory: string | URL): SessionStorefileSessionStore(
  directory: string | URL
): SessionStore

import { createClient, fileSessionStore } from "@neontechspace/fluxerly"

export function resumableClient(token) {
    return createClient({ token, sharding: { totalShards: "auto", sessions: fileSessionStore("sessions") } })
}

import { createClient, fileSessionStore } from "@neontechspace/fluxerly"

export function resumableClient(token: string) {
    return createClient({ token, sharding: { totalShards: "auto", sessions: fileSessionStore("sessions") } })
}

supervisor#

const supervisor: SupervisorTools

import { supervisor } from "@neontechspace/fluxerly"

export const workers = supervisor.create({
    entry: "/srv/bot-worker.js",
    totalShards: 2,
    assignments: [
        { id: "one", shardIds: [0] },
        { id: "two", shardIds: [1] },
    ],
})

import { supervisor } from "@neontechspace/fluxerly"

export const workers = supervisor.create({
    entry: "/srv/bot-worker.js",
    totalShards: 2,
    assignments: [
        { id: "one", shardIds: [0] },
        { id: "two", shardIds: [1] },
    ],
})

IdentifyCoordinator#

interface IdentifyCoordinator

permit(
    shardId: number,
    totalShards: number,
    signal: AbortSignal
): Promise<void>permit(
  shardId: number,
  totalShards: number,
  signal: AbortSignal
): Promise<void>

SessionSnapshot#

interface SessionSnapshot

resumeUrl#

Gateway URL the session connected to

Fluxer publishes no separate resume URL, so this is the discovered gateway endpoint. A loaded snapshot is used only when it matches the endpoint the new client discovers

string

savedAt#

Wall-clock time the snapshot was taken, in Unix epoch milliseconds, after the session's socket closed

number

sequence#

Last dispatch sequence this client received on the session, a non-negative integer

number

sessionId#

Session ID from Fluxer's READY, or empty in the copy that marks a loaded snapshot as used

string

totalShards#

Total shard count of the plan the session identified with

A session belongs to that plan, so a loaded snapshot is used only when the new client's plan has the same total

number

SessionStore#

interface SessionStore

load(shardId: number): Promise<SessionSnapshot | undefined>load(shardId: number): Promise<
  SessionSnapshot | undefined
>

save(shardId: number, snapshot: SessionSnapshot): Promise<void>save(
  shardId: number,
  snapshot: SessionSnapshot
): Promise<void>

ShardRecoveryDiagnostic#

interface ShardRecoveryDiagnostic

attempt#

One-based connection attempt number for this shard's managed run, counting startup and later recovery

During a retry delay, identifies the attempt that ended, not the next attempt

number

phase#

Whether this attempt belongs to initial startup or established-session recovery

"startup" | "recovery"

retryDelayMs#

Scheduled retry wait in milliseconds, or null while the current attempt is not waiting

This is not a remaining countdown

number | null

ShardState#

interface ShardState

gatewayLatencyMs#

Latest current-connection heartbeat round trip in milliseconds, or null when no measurement is current

number | null

recovery#

Current safe connection attempt or retry snapshot, or null when this shard is not attempting or waiting

ShardRecoveryDiagnostic | null

sessionEpoch#

Identifies this shard's current gateway session within the client

It is 0 until the shard's first new session and gets a new value, never used before by this client and larger than every earlier one, each time the shard starts a new session, including the shards of a larger plan after a move. A Resume, which replays every missed event, keeps it, and so does resuming a saved session after a restart, so a process that resumes a saved session reports 0 until that shard next starts a new session. A changed value means the events of that shard's communities between the two sessions may have been missed. Fluxer then sends each of those communities again as a guildCreate event, and a community that is unavailable sends guildDelete instead. This is the shard's current value, which can already be newer than the session of an event a handler is still processing, because events wait in each handler's queue. To tell which session an event belongs to, compare EventContext.sessionEpoch, which keeps the value from when the client accepted the event

number

shardId#

This client's local shard ID, retained in the configured local order

number

state#

Current connection status for this shard

ConnectionState

ShardingOptions#

interface ShardingOptions

identify optional#

Coordinate new-session Identify commands with other processes, for example through a shared lock service

The coordinator then owns pacing: The SDK waits for permit before each Identify and adds no spacing of its own. Resume never waits for it. See IdentifyCoordinator

IdentifyCoordinator

refillCaches optional#

Whether a shard that resumes a session loaded from sessions refills the enabled community, role and channel caches through REST, default true

Fluxer calls a community a guild. Resume replays missed dispatches but sends no fresh community snapshot, so without the refill those caches contain only observations from replay, later events and requests. Once every shard is ready, the SDK lists the bot's communities and fetches each one on a resumed shard, one request at a time, so application requests keep the other REST slots and every request respects rate limits. It logs lifecycle.cacheRefill when done, at Warn when communities failed or the refill stopped early. A community list page that does not move past the previous one stops the refill instead of paging forever. Set false to skip the refill, for example for a bot that reads no cache

boolean

Default

JavaScriptTypeScript

true

true

sessions optional#

Keep resumable sessions across process restarts, so a restart within Fluxer's 60-second resume window can Resume instead of starting new sessions

A fallback to a new session clears any partial restored replay from that shard's community caches and dependent resources. A successful Resume retains it. See SessionStore

SessionStore

shardIds optional#

Immutable non-empty local IDs, each unique integer from 0 through totalShards minus one

Omit to own every ID in ascending order. Automatic sizing requires omission

readonly number[]

totalShards#

Immutable total gateway shards for this bot, an integer from 1 through 16,384 shared by every process serving it

Fluxer closes a shard with 4011 (sharding required) when it serves more than 2,500 communities, and with an explicit total that closure ends the client with a ConnectionError. The value "auto" lets this client size the plan itself and own every shard, as the sharding value "auto" does, while keeping identify and sessions available

number | "auto"

Supervisor#

interface Supervisor

shutdown(): ResultAsync<void, never>

start(): ResultAsync<void, SupervisorError>start(): ResultAsync<
  void, SupervisorError
>

status(): SupervisorStatus

waitForClose(): ResultAsync<void, SupervisorError>waitForClose(): ResultAsync<
  void, SupervisorError
>

waitForReady(options?: SupervisorWaitOptions): ResultAsync<
    void,
    ConfigurationError | SupervisorError | CancelledError
>waitForReady(
  options?: SupervisorWaitOptions
): ResultAsync<
  void,
  | ConfigurationError
  | SupervisorError
  | CancelledError
>

SupervisorAssignment#

interface SupervisorAssignment

shardIds#

Fixed shard IDs owned by this child, in configured order

Shards outside this list are not owned by this child

readonly number[]

totalShards#

Immutable total shard count used by this supervisor

number

SupervisorAssignmentOptions#

interface SupervisorAssignmentOptions

id#

Unique nonblank local identifier, at most 128 characters, shown in lifecycle failures and status snapshots

string

shardIds#

One or more unique shard IDs from zero through totalShards minus one

readonly number[]

SupervisorChildContext#

interface SupervisorChildContext

assignment#

Fixed assignment for this child process

It cannot be changed during this run

SupervisorAssignment

client#

Client created and owned by child.run

Register application behavior here rather than starting or stopping this client

Client

signal#

Signal aborted when the parent requests shutdown or its message channel disconnects

Setup work should check this signal and stop when it is aborted. The helper cannot forcibly cancel a JavaScript promise

AbortSignal

SupervisorChildDiagnostics#

interface SupervisorChildDiagnostics

client#

The child client's diagnostics at the time it sent them

See ClientDiagnostics

ClientDiagnostics

receivedAt#

Parent wall-clock time the snapshot arrived, in Unix epoch milliseconds

An old value means the child stopped reporting

number

SupervisorChildOptions#

interface SupervisorChildOptions

clientOptions optional#

Every client setting except token is read by property name and copied before configure, including inherited and non-enumerable properties

The supervisor assigns the shards, so sharding accepts only sessions. Runtime validation rejects a token, a shard plan or identify coordinator in sharding, and any other own key that is not a client option, with ConfigurationError

& Omit<ClientOptions<undefined>, "token" | "sharding">
& { readonly sharding?: SupervisorChildSharding }& Omit<
    ClientOptions<undefined>,
    "token" | "sharding"
  >
& {
    readonly sharding?:
      SupervisorChildSharding
  }

configure#

Register subscriptions and local application behavior before the helper calls client.run

Return when setup is finished, not when the bot stops. Do not call client.run, connect or shutdown here. A thrown error, rejected promise or returned Err rejects child.run with SdkDefect code application.defect, whose cause is an ApplicationError with source "supervisor child configure" and the original value as its cause. A parent stop can finish child.run without waiting for this promise. Setup must check context.signal to avoid continuing afterward

(context: SupervisorChildContext) => unknown(context: SupervisorChildContext)
  => unknown

token#

Bot token for the client created by child.run, such as process.env.FLUXER_BOT_TOKEN

The parent assignment does not supply this credential. A missing or blank value fails child.run with ConfigurationError once the assignment arrives, as createClient does, and the parent sees the child fail during configuration

string | undefined

SupervisorChildSharding#

interface SupervisorChildSharding

sessions optional#

Keep this child's resumable sessions across process restarts, as the client option sharding.sessions does

A deploy that stops the supervisor and starts it again within Fluxer's 60-second resume window then resumes each shard instead of starting a new session. Resumable snapshots are saved only when the child shuts down normally, so a restart after a crash starts new sessions. The child saves while it shuts down, so saves must finish within the supervisor option shutdownTimeoutMs, after which the parent force-terminates the child. See SessionStore

SessionStore

SupervisorChildStatus#

interface SupervisorChildStatus

assignment#

Immutable assignment retained by this supervisor

SupervisorAssignment

connectionState#

Last aggregate gateway connection state reported by the current child process after configuration

Null before its first accepted report, after exit or when IPC is unavailable. Reports from different children are not simultaneous

ConnectionState | null

diagnostics#

Latest client diagnostics the current child process sent, or null before its first snapshot, after exit or when IPC is unavailable

A running child sends one when it finishes configuration and then every diagnosticsIntervalMs

SupervisorChildDiagnostics | null

generation#

Fork attempts for this assignment, starting at zero before startup and incrementing even if a fork fails

number

id#

Stable child identifier from the original assignment

string

pid#

Current owned child process ID, or null before a process starts or after verified exit

number | null

restarts#

Replacement attempts used from this child's current budget, including a replacement waiting for its delay

A restart that follows a healthy run of healthyResetMs counts from one again

number

state#

Current local lifecycle state

SupervisorChildState

SupervisorFileUrl#

interface SupervisorFileUrl

href#

Complete file URL string

string

protocol#

URL protocol, which must be file:

string

SupervisorIdentifyOptions#

interface SupervisorIdentifyOptions

coordinator optional#

Share Fluxer's Identify budget with other supervisors and clients, for example across several hosts, through the same IdentifyCoordinator a client accepts in sharding.identify

Before each grant the parent calls permit with the child's shard ID, the supervisor's total shard count and a signal, and grants the child only after the promise resolves. The coordinator then owns pacing, so the parent adds no spacing of its own. The signal aborts when the child no longer needs the permit, for example when its connection attempt times out, it exits or the supervisor stops. A rejection or thrown error is logged in full at Error with code supervisor.identifyPermitFailed, and the child retries its connection attempt as after a network failure. Creation copies the permit function, bound to its object

IdentifyCoordinator

minimumSpacingMs optional#

Minimum interval between child-confirmed fresh Identify sends in milliseconds, an integer from 1,000 through 2,147,483,647

Cannot be combined with coordinator

number

Default

JavaScriptTypeScript

1000

1000

SupervisorOptions#

interface SupervisorOptions

args optional#

Program arguments for every owned child, at most 64 strings of at most 4,096 characters each

readonly string[]

Default

JavaScriptTypeScript

[]

[]

assignments optional#

One to totalShards fixed child assignments, with unique IDs and no overlapping shard IDs

Unassigned shards remain application-owned. Cannot be combined with processes or shardsPerProcess

readonly SupervisorAssignmentOptions[]

childEnvironment optional#

Up to 64 explicit string environment overrides copied over the inherited environment at creation

Keys use ASCII letters, digits and underscores, starting with a letter or underscore. Values have at most 4,096 characters. The parent retains this launch snapshot, including any credentials supplied there, until owned children exit. Status and errors do not contain these settings

Readonly<Record<string, string>>

childOutput optional#

How child standard output and error reach this process

"inherit" | "prefix" | "ignore"

The default, prefix, forwards each child line through this process in the format of the stream it goes to. Default-API children log JSON with no color, unless FLUXERLY_LOG_FORMAT or FLUXERLY_LOG_COLOR is set in the child environment. An Effect API child sends its records to Effect's logger unless its logging.format option is set, so set that option to json to forward structured records. In pretty format each SDK record prints as a readable line and each line gets a label: [shard N] for a child owning one shard, otherwise [child id]. Other text keeps its content behind the label. In json format the output stays valid JSON Lines: A child's SDK record gains a fields.child entry, another JSON object passes through unchanged, and other text becomes a supervisor.childOutput record. Each stream decides on its own, so with a terminal on standard output and standard error redirected to a file, standard output shows readable lines and the file receives the child's records with their level, code and fields. Lines longer than 262,144 characters are truncated with a marker, and child output pauses while this process's output applies backpressure. Exit handling waits up to one second after a child exits for its output to drain. A failed read of a child stream logs supervisor.outputFailed at Warn and stops forwarding that stream

The value inherit shares this process's streams without labels, and ignore discards child output

Default

JavaScriptTypeScript

"prefix"

"prefix"

diagnosticsIntervalMs optional#

How often each running child sends its client diagnostics to the parent, in milliseconds, an integer from 1,000 through 2,147,483,647

A child also sends one snapshot as soon as it finishes configuration. See SupervisorChildStatus

number

Default

JavaScriptTypeScript

5000

5000

entry#

Absolute module path string or file-URL object passed to every Node child-process fork

A file-URL string is not accepted

string | SupervisorFileUrl

execArgv optional#

Node executable arguments for every owned child

Omit to copy the parent's process.execArgv. At most 64 strings of at most 4,096 characters each. The SDK's development-only fluxerly-source condition is removed

readonly string[]

identify optional#

Parent-side fresh-Identify pacing shared by these children, or a coordinator shared with other processes

SupervisorIdentifyOptions

instance optional#

Fluxer instance for the community count when totalShards is "auto", as the client option instance

Rejected otherwise

InstanceOptions

logging optional#

Records for the automatic plan, child spawn, exit with code and signal, crash, restart and refused Identify permits, in the supervisor log category

A missed startup deadline, a forced termination and an unconfirmed Identify grant are each logged before the supervisor acts on them. Accepts the same settings as client logging. Default output prints these records at Info and higher. The native supervisor sends them to the Effect logger of the context that creates it unless a sink or format is set

LoggingOptions

processes optional#

Number of child processes that share every shard, an integer from 1 through 16,384

With a numeric totalShards it can be at most totalShards. With "auto", a plan with fewer shards than processes starts one process per shard

number

restart optional#

Replacement policy for unexpected local child exits

Omit it to restart with the defaults of SupervisorRestartOptions, or set false so that one unexpected exit stops the whole supervisor

false | SupervisorRestartOptions

shardsPerProcess optional#

Shards per child process, an integer from 1 through 16,384

The last process owns the remainder when the total does not divide evenly

number

shutdownTimeoutMs optional#

Time allowed for an owned child to exit after a stop request, in milliseconds, before the parent force-terminates it

A positive safe integer no greater than 2,147,483,647. Shutdown still awaits the process exit, which can take longer. A stopping child first lets running handlers and REST requests finish for up to this time minus one second, as the client shutdown option drainMs does, and keeps that second to close its connections. IPC is Node's parent-child message channel. If a current child loses IPC, it has this long to exit naturally. If that window expires, the supervisor fails with closed and force-terminates that child without a second grace period. Other owned children receive their normal stop request and grace period

number

Default

JavaScriptTypeScript

5000

5000

startupTimeoutMs optional#

Time allowed for each child to receive its assignment and finish configure, in milliseconds, including replacement children

This does not wait for the gateway READY event that establishes a connected session. With totalShards "auto" the community count before the first child starts has its own deadline of the same length. A positive safe integer no greater than 2,147,483,647. Timeout fails the supervisor, which stops its children and awaits their exit

number

Default

JavaScriptTypeScript

30000

30000

token optional#

Bot token used only to count the bot's communities when totalShards is "auto", such as process.env.FLUXER_BOT_TOKEN

Children still receive their own token through supervisor.child.run. Required with "auto" and rejected otherwise

string

totalShards#

Total gateway shard count for this bot, an integer from 1 through 16,384

Other processes serving it must use the same total. The value "auto" counts the bot's communities once, at start, by paging GET /users/@me/guilds within startupTimeoutMs, and uses one shard per 2,000 communities, from 1 through 16,384 shards. The count needs the token option, and it works only with processes or shardsPerProcess, because fixed assignments need a known total. A failed count fails start with SupervisorError reason shardCount, whose cause is the AuthenticationError, RateLimitError, ConnectionTimeoutError or ConnectionError of the count. Until the count completes, status lists no children. Restarts keep the plan. When Fluxer closes a child's shard with 4011 (sharding required) because the bot outgrew the plan, the supervisor stops every child, counts again and starts children for a larger plan, as a client with sharding "auto" does, logging a supervisor.resharded Warn record. Events sent during the move are missed. After 3 moves within an hour, or at 16,384 shards, a further 4011 fails the supervisor with reason closed instead

number | "auto"

transport optional#

HTTP implementation and User-Agent for the community count when totalShards is "auto", as the client option transport

Rejected otherwise

TransportOptions

SupervisorRestartOptions#

interface SupervisorRestartOptions

healthyResetMs optional#

Milliseconds a child must run after finishing configuration for its next exit to start a fresh restart budget, a positive safe integer no greater than 2,147,483,647

The supervisor.restart record then has fields.budgetReset true

number

Default

JavaScriptTypeScript

60000

60000

maxAttempts optional#

Maximum replacement attempts per child, an integer from 0 through 100

Zero permits no replacement

number

Default

JavaScriptTypeScript

3

3

maxDelayMs optional#

Maximum exponential replacement delay in milliseconds, a positive safe integer no greater than 2,147,483,647

number

Default

JavaScriptTypeScript

30000

30000

minDelayMs optional#

First replacement delay in milliseconds, a positive safe integer no greater than maxDelayMs

number

Default

JavaScriptTypeScript

1000

1000

SupervisorStatus#

interface SupervisorStatus

children#

One snapshot per child assignment, in assignment order, including children with no current process

Empty with totalShards "auto" until start has counted the plan

readonly SupervisorChildStatus[]

state#

Current supervisor lifecycle state

SupervisorState

SupervisorTools#

interface SupervisorTools

child#

Child-module helper

Call run inside the module selected by the parent's entry option

{
    run(options: SupervisorChildOptions): ResultAsync<
        void,
        | ConfigurationError | SupervisorChildError | CancelledError
        | ConnectError
    >
}{
  run(
    options: SupervisorChildOptions
  ): ResultAsync<
    void,
    | ConfigurationError
    | SupervisorChildError
    | CancelledError | ConnectError
  >
}

create(options: SupervisorOptions): Supervisorcreate(
  options: SupervisorOptions
): Supervisor

SupervisorWaitOptions#

interface SupervisorWaitOptions

signal optional#

Cancels only this wait

An already-aborted signal cancels without starting, stopping or restarting any child

OperationSignal

SupervisorChildState#

type SupervisorChildState =
    | "idle" | "starting" | "running" | "restarting" | "stopping"
    | "closed" | "failed"type SupervisorChildState =
    | "idle" | "starting"
    | "running" | "restarting"
    | "stopping" | "closed"
    | "failed"

SupervisorState#

type SupervisorState =
    | "idle" | "starting" | "running" | "stopping" | "closed"
    | "failed"type SupervisorState =
    | "idle" | "starting"
    | "running" | "stopping"
    | "closed" | "failed"