Documentation / @etherfold/browser / HostedIndexerSpec

Type Alias: HostedIndexerSpec<ABI, ProcessResultType, ProcessorConfig>

HostedIndexerSpec<ABI, ProcessResultType, ProcessorConfig> = BrowserGenerationSpec<ABI, ProcessResultType, ProcessorConfig> & PublishedStartOptions<ABI> & object

Defined in: packages/browser/src/host/serve.ts:120

WHAT AN APP HANDS ITS HOST, wherever the host runs.

It is the generation spec createIndexerState already takes, PLUS what that function takes at init (a provider, a source, a config).

What the entry must hold, and what a tab may hand over instead

The CODE must be here: createState, createProcessor, a processor module, a keepStream. Code cannot be cloned, so it is imported where the fold runs (ADR-0082). The PROVIDER and the cloneable SETTINGS (HostSettings: source, config, publication, catchUpWithinSeconds, seed, promotion) may be here OR come from the tab that connects (connectToIndexerHost(access, {provider, settings})): a provider crosses as a MessagePort speaking @eip-1193/over-port, which is how a wallet's provider, or a node running in ANOTHER worker, reaches a worker-hosted indexer.

The host STARTS once it has a provider and a source, from wherever they came. An entry that holds both starts at once, as it always did; one that leaves either out WAITS (phase: 'waiting') for a tab to hand it over. A value given in both places, or sent by a tab once the host has started, must AGREE with the one held, or the tab's connect is refused naming the fields (HostSettingsConflictError, see settleHostSettings).

Type Declaration

claimWithinSeconds?

optional claimWithinSeconds?: number

How long this host waits for a generation's WRITER CLAIM, in seconds. Defaults to DEFAULT_CLAIM_WITHIN_SECONDS (ten).

Handed to createState as a signal to forward to openForWriting. A claim that never lands is the difference between a host that REFUSES -- which this one reports as phase: 'refused' with a failure the tab reads over the port -- and one that says waiting for ever. See utils/claim.ts.

config?

optional config?: ProvidedIndexerConfig<ABI>

processorConfig?

optional processorConfig?: ProcessorConfig

The processor's own configuration, where it takes one.

promotion?

optional promotion?: PromotionConfig

Passed through and never defaulted here, exactly as createIndexerState passes it through.

provider?

optional provider?: EIP1193ProviderWithoutEvents

The chain, built HERE (from an RPC URL, say), or LEFT OUT for the tab that connects to hand over as a port. Given in both places, the tab's is refused.

query?

optional query?: HostQueryHandler

THE QUERY HANDLER this host answers the port's query case with (ADR-0099), or absent for a host that answers no query. OPT-IN, so a worker bundle that does not query carries no query language: for GraphQL, pass graphqlQueryHandler() from @etherfold/graphql/worker, and hold workerExecutor(port) in the tab. See HostQueryHandler.

Code, so it is the entry's to pass and never a tab's to send.

source?

optional source?: IndexingSource<ABI>

What to fold. Left out, the host waits for a tab to send it (HostSettings.source).

tabElection?

optional tabElection?: TabElection

ONE TAB INDEXES AND THE OTHERS READ (ADR-0097): the name of the Web Lock this app's hosts elect their indexing host with. ON only together with the spec's reader factory (openState) and where the worker has navigator.locks; otherwise this host behaves exactly as it did without it.

The lock is taken HERE, inside the worker that indexes, so the browser releases it when that worker (or the tab that owns it) dies, crash included. A host that finds it held is a READER: it answers reads from openState's store, forwards the leader's state-moved signal and reports the leader's progress (HostProgress.election), and queues. When the lock is released it builds its generation through createState, claims, and indexes forward from the stored cursor. A SharedWorker host takes the same lock through the same code, uncontended by its own tabs, which is what lets it and dedicated-worker hosts of one app share one election.

The FOREGROUND TAKEOVER (TabElection.foregroundTakeover, on by default) is driven by the visibility the tab reports over the port (connectToIndexerHost does, from document): a dedicated-worker reader whose tab stayed visible past the settle time while the leader is hidden takes the lease, and a leader whose lease is taken stops its driver, abandons its in-flight batch, lets go of its container and reads again. A SHAREDWORKER host does not take part: it is one indexer for all its tabs rather than a background tab, so it publishes no visibility (and is never displaced) and never takes the lease.

tipIntervalInSeconds?

optional tipIntervalInSeconds?: number

How long the driver rests once the fold is AT THE TIP, in seconds. Defaults to four, which is createIndexerState's auto-index interval.

Type Parameters

ABI

ABI extends Abi

ProcessResultType

ProcessResultType

ProcessorConfig

ProcessorConfig = undefined