ClusterService

@webda/core

---

Abstract Class: ClusterService<T>

Defined in: packages/core/src/services/cluster.service.ts:176

Elect one leader among the instances of an application

The election loop acquires or renews the lease at start, then renewInterval after each attempt. Subclasses provide the lease with acquireOrRenew and release.

A leader stops leading before its lease can expire for the others:

• when an attempt fails (error, lease lost, or no answer within leaseDuration - renewInterval)
• when no attempt succeeded before its deadline: the start of the last successful attempt plus (leaseDuration + renewInterval) / 2. The lease, written after that start, outlives the deadline by at least (leaseDuration - renewInterval) / 2; an attempt that succeeds after its own deadline counts as failed.

Extends

• Service<T>

Extended by

• StoreClusterService

Type Parameters

T

T extends ClusterServiceParameters = ClusterServiceParameters

Implements

• Cluster

Constructors

Constructor

new ClusterService<T>(name, params): ClusterService<T>

Defined in: packages/core/src/services/service.ts:205

Create a new Service instance

Service

Parameters

name

string

The name of the service

params

T

The parameters block define in the configuration file

Returns

ClusterService<T>

Inherited from

Service.constructor

Properties

_compiledCapabilities

protected _compiledCapabilities: Record<string, any> = {}

Defined in: packages/core/src/services/iservice.ts:61

Capabilities detected at compile-time from @WebdaCapability-tagged interfaces.

Populated during Service.resolve by reading the service's entry in webda.module.json. Each key is a capability name (e.g., "request-filter"), and the value is an empty object {} by default. Override getCapabilities to provide capability-specific configuration or to conditionally disable capabilities.

See

getCapabilities

Inherited from

Service._compiledCapabilities

---

[WEBDA_EVENTS]

[WEBDA_EVENTS]: object

Defined in: packages/core/src/services/service.ts:179

Set the Webda events here

Inherited from

Service.[WEBDA_EVENTS]

---

deadlineTimer?

protected optional deadlineTimer?: Timeout

Defined in: packages/core/src/services/cluster.service.ts:192

Step down when no attempt succeeded before the deadline

---

leading

protected leading: boolean = false

Defined in: packages/core/src/services/cluster.service.ts:186

Whether this instance holds the lease

---

logger

protected logger: Logger

Defined in: packages/core/src/services/service.ts:192

Logger with class context

Inherited from

Service.logger

---

metrics?

protected optional metrics?: object

Defined in: packages/core/src/services/service.ts:196

Get metrics

Inherited from

Service.metrics

---

name

readonly name: string

Defined in: packages/core/src/services/iservice.ts:35

Name

Inherited from

Service.name

---

parameters

readonly parameters: T

Defined in: packages/core/src/services/iservice.ts:39

Parameters

Inherited from

Service.parameters

---

registrations

protected registrations: LeaderRegistrations

Defined in: packages/core/src/services/cluster.service.ts:194

whenLeader registrations

---

running

protected running: boolean = false

Defined in: packages/core/src/services/cluster.service.ts:188

Whether the election loop runs

---

timer?

protected optional timer?: Timeout

Defined in: packages/core/src/services/cluster.service.ts:190

Next attempt

---

createConfiguration?

static optional createConfiguration?: (params) => any

Defined in: packages/core/src/services/iservice.ts:44

Create configuration set by the application on load

Parameters

params

any

Returns

any

Inherited from

Service.createConfiguration

---

filterConfiguration?

static optional filterConfiguration?: (params) => any

Defined in: packages/core/src/services/iservice.ts:49

Create configuration set by the application on load

Parameters

params

any

Returns

any

Inherited from

Service.filterConfiguration

---

Parameters

static Parameters: typeof ClusterServiceParameters = ClusterServiceParameters

Defined in: packages/core/src/services/cluster.service.ts:183

Parameters

Overrides

Service.Parameters

Methods

__clean()

abstract __clean(): Promise<void>

Defined in: packages/core/src/services/service.ts:539

Clean the service data, can only be used in test mode

Returns

Promise<void>

Inherited from

Service.__clean

---

acquireOrRenew()

abstract protected acquireOrRenew(): Promise<boolean>

Defined in: packages/core/src/services/cluster.service.ts:204

Acquire the lease, or renew it when held

Returns

Promise<boolean>

whether this instance holds the lease

Throws

when the lease cannot be read or written: this instance stops leading

---

addListener()

addListener<Key>(eventName, listener): this

Defined in: packages/core/src/events/asynceventemitter.ts:90

Add listener

Type Parameters

Key

Key extends never

Parameters

eventName

Key

the event name

listener

(event) => void | Promise<void>

the event listener

Returns

this

this for chaining

See

EventEmitter.addListener

Inherited from

Service.addListener

---

addRoute()

protected addRoute(url, methods, executer, openapi?, override?): void

Defined in: packages/core/src/services/service.ts:400

Add a route dynamicaly

Parameters

url

string

of the route can contains dynamic part like {uuid}

methods

HttpMethodType[]

the HTTP methods

executer

Function

Method to execute for this route

openapi?

OpenAPIWebdaDefinition = {}

the OpenAPI specification

override?

boolean = false

whether to override existing

Returns

void

Inherited from

Service.addRoute

---

attempt()

protected attempt(): Promise<void>

Defined in: packages/core/src/services/cluster.service.ts:277

Acquire or renew the lease once, then schedule the next attempt

The callbacks are not awaited: a long fn never delays the renewals.

Returns

Promise<void>

---

authorizeClientEvent()

authorizeClientEvent(_event, _context): boolean

Defined in: packages/core/src/services/service.ts:353

Authorize a public event subscription

Parameters

_event

string

the event name

_context

OperationContext

the execution context

Returns

boolean

true if the condition is met

Inherited from

Service.authorizeClientEvent

---

computeParameters()

computeParameters(): void

Defined in: packages/core/src/services/service.ts:214

Used to compute or derivate input parameter to attribute

Returns

void

Deprecated

Inherited from

Service.computeParameters

---

emit()

emit<Key>(event, data): Promise<void>

Defined in: packages/core/src/services/service.ts:520

Emit the event with data and wait for Promise to finish if listener returned a Promise

Type Parameters

Key

Key extends never

Parameters

event

Key

the event name

data

object[Key]

the data to process

Returns

Promise<void>

Inherited from

Service.emit

---

getCapabilities()

getCapabilities(): Record<string, any>

Defined in: packages/core/src/services/iservice.ts:89

Return the capabilities of this service.

By default returns capabilities detected at compile-time from

Returns

Record<string, any>

the result

Webda Capability-tagged

interfaces in webda.module.json.

Override to disable capabilities based on configuration:

getCapabilities() {
  const caps = super.getCapabilities();
  if (!this.parameters.enabled) delete caps["request-filter"];
  return caps;
}

Inherited from

Service.getCapabilities

---

getClientEvents()

getClientEvents(): string[]

Defined in: packages/core/src/services/service.ts:341

Return the events that an external system can subscribe to

Returns

string[]

the list of results

Inherited from

Service.getClientEvents

---

getInstanceId()

getInstanceId(): string

Defined in: packages/core/src/services/cluster.service.ts:222

Returns

string

Implementation of

Cluster.getInstanceId

---

getLeadingWindow()

protected getLeadingWindow(): number

Defined in: packages/core/src/services/cluster.service.ts:314

Get milliseconds after the start of a successful attempt during which this instance leads:

Returns

number

milliseconds after the start of a successful attempt during which this instance leads: (leaseDuration + renewInterval) / 2, between the next attempt and the expiry of the lease

---

getMaxListeners()

getMaxListeners(): number

Defined in: packages/core/src/events/asynceventemitter.ts:97

Returns

number

Inherited from

Service.getMaxListeners

---

getMetric()

getMetric<T>(type, configuration): T

Defined in: packages/core/src/services/service.ts:323

Add service name label

Type Parameters

T

T = Gauge<string> | Counter<string> | Histogram<string>

Parameters

type

CustomConstructor<T, [MetricConfiguration<T>]>

the type to look up

configuration

MetricConfiguration<T>

the configuration

Returns

T

the result

Inherited from

Service.getMetric

---

getName()

getName(): string

Defined in: packages/core/src/services/service.ts:530

Get service name

Returns

string

the result string

Inherited from

Service.getName

---

getOpenApiReplacements()

getOpenApiReplacements(): any

Defined in: packages/core/src/services/service.ts:429

Return variables for replacement in openapi

Returns

any

the result

Inherited from

Service.getOpenApiReplacements

---

getOperationId()

getOperationId(id): string

Defined in: packages/core/src/services/service.ts:387

If undefined is returned it cancel the operation registration

Parameters

id

string

the identifier

Returns

string

the result

Inherited from

Service.getOperationId

---

getParameters()

getParameters(): T

Defined in: packages/core/src/services/service.ts:222

Get the service parameters

Returns

T

the result

Inherited from

Service.getParameters

---

getService()

getService<T>(name): ServicesMap[T]

Defined in: packages/core/src/services/service.ts:313

Get a service by name

Type Parameters

T

T extends keyof ServicesMap

Parameters

name

T

the name to use

Returns

ServicesMap[T]

the result map

Deprecated

Use useService, might reconsider

Inherited from

Service.getService

---

getState()

getState(): ServiceStates

Defined in: packages/core/src/services/service.ts:185

Get the current state

Returns

ServiceStates

the result

Inherited from

Service.getState

---

getUrl()

getUrl(url, _methods): string

Defined in: packages/core/src/services/service.ts:364

Return the full path url based on parameters

Parameters

url

string

relative url to service

_methods

HttpMethodType[]

in case we need filtering (like Store)

Returns

string

absolute url or undefined if need to skip the Route

Inherited from

Service.getUrl

---

init()

init(): Promise<ClusterService<T>>

Defined in: packages/core/src/services/cluster.service.ts:245

Start the election loop

Returns

Promise<ClusterService<T>>

once the first attempt is done

Overrides

Service.init

---

initMetrics()

initMetrics(): void

Defined in: packages/core/src/services/service.ts:303

Init the metrics

Returns

void

Inherited from

Service.initMetrics

---

initOperations()

initOperations(): void

Defined in: packages/core/src/services/service.ts:459

Init the operations from

Returns

void

Operation

decorators on this service

Inherited from

Service.initOperations

---

isLeader()

isLeader(): boolean

Defined in: packages/core/src/services/cluster.service.ts:217

Returns

boolean

Implementation of

Cluster.isLeader

---

listeners()

listeners(eventName): Function[]

Defined in: packages/core/src/events/asynceventemitter.ts:195

Get all listeners for an event

Parameters

eventName

never

the event name

Returns

Function[]

the list of results

Inherited from

Service.listeners

---

loadCapabilities()

protected loadCapabilities(): void

Defined in: packages/core/src/services/service.ts:283

Load capabilities from webda.module.json metadata into _compiledCapabilities.

Called during resolve after dependency injection. Reads the service's type name from parameters, looks it up in the application's module metadata (moddas or beans section), and populates _compiledCapabilities with an empty object for each declared capability name.

Fails silently if the application is not available (e.g., in unit tests where services are instantiated without a full application context).

Returns

void

Example

// If webda.module.json contains:
// { "moddas": { "MyApp/HawkService": { "capabilities": ["request-filter", "cors-filter"] } } }
// Then after resolve(), this.getCapabilities() returns:
// { "request-filter": {}, "cors-filter": {} }

See

getCapabilities

Inherited from

Service.loadCapabilities

---

log()

log(level, ...args): void

Defined in: packages/core/src/services/service.ts:561

Log operation

Parameters

level

WorkerLogLevel

to log

args

...any[]

additional arguments

Returns

void

Inherited from

Service.log

---

off()

off<Key>(eventName, listener): this

Defined in: packages/core/src/events/asynceventemitter.ts:152

Perform off

Type Parameters

Key

Key extends never

Parameters

eventName

Key

the event name

listener

(event) => void

the event listener

Returns

this

this for chaining

See

EventEmitter.off

Inherited from

Service.off

---

on()

on<Key>(eventName, listener): this

Defined in: packages/core/src/events/asynceventemitter.ts:128

Perform on

Type Parameters

Key

Key extends never

Parameters

eventName

Key

the event name

listener

(event) => void

the event listener

Returns

this

this for chaining

See

EventEmitter.once

Inherited from

Service.on

---

once()

once<Key>(eventName, listener): this

Defined in: packages/core/src/events/asynceventemitter.ts:116

Perform once

Type Parameters

Key

Key extends never

Parameters

eventName

Key

the event name

listener

(event) => void

the event listener

Returns

this

this for chaining

See

EventEmitter.once

Inherited from

Service.once

---

operationSchemaName()

protected operationSchemaName(method, side): string

Defined in: packages/core/src/services/service.ts:441

Schema of an operation side: <service name>.<method>.<side> when the application knows it, else the one the build writes, <class>.<method>.<side>, for the class or its nearest ancestor that has it (a service configured under another name than its class)

Parameters

method

string

the method name

side

"input" | "output"

input or output

Returns

string

the schema name

Inherited from

Service.operationSchemaName

---

release()

abstract protected release(): Promise<void>

Defined in: packages/core/src/services/cluster.service.ts:209

Release the held lease, so another instance takes over without waiting for its expiry

Returns

Promise<void>

---

removeAllListeners()

removeAllListeners<Key>(eventName?): this

Defined in: packages/core/src/events/asynceventemitter.ts:162

Remove all listeners

Type Parameters

Key

Key extends never

Parameters

eventName?

Key

the event name

Returns

this

this for chaining

See

EventEmitter.removeAllListeners

Inherited from

Service.removeAllListeners

---

removeListener()

removeListener<Key>(eventName, listener): this

Defined in: packages/core/src/events/asynceventemitter.ts:140

Remove listener

Type Parameters

Key

Key extends never

Parameters

eventName

Key

the event name

listener

(event) => void

the event listener

Returns

this

this for chaining

See

EventEmitter.removeListener

Inherited from

Service.removeListener

---

resolve()

resolve(): this

Defined in: packages/core/src/services/cluster.service.ts:230

Adopt the free whenLeader registrations made before this service was created

Returns

this

this

Overrides

Service.resolve

---

setLeading()

protected setLeading(leading): Promise<void>

Defined in: packages/core/src/services/cluster.service.ts:343

Change the leadership, running the callbacks of the registrations

Parameters

leading

boolean

whether this instance leads

Returns

Promise<void>

once the callbacks settled

---

setMaxListeners()

setMaxListeners(n): this

Defined in: packages/core/src/events/asynceventemitter.ts:104

Parameters

n

number

Returns

this

Inherited from

Service.setMaxListeners

---

stop()

stop(): Promise<void>

Defined in: packages/core/src/services/cluster.service.ts:255

Stop the election loop, release the lease when held and call the deregisteredFns

Returns

Promise<void>

Overrides

Service.stop

---

toJSON()

toJSON(): string

Defined in: packages/core/src/services/service.ts:499

Prevent service to be serialized

Returns

string

the result

Inherited from

Service.toJSON

---

toString()

toString(): string

Defined in: packages/core/src/services/service.ts:238

Return service representation

Returns

string

the result

Inherited from

Service.toString

---

whenLeader()

whenLeader(fn, deregisteredFn?): () => void

Defined in: packages/core/src/services/cluster.service.ts:212

Parameters

fn

LeaderCallback

deregisteredFn?

LeaderCallback

Returns

() => void

Implementation of

Cluster.whenLeader

---

withTimeout()

protected withTimeout<R>(attempt): Promise<R>

Defined in: packages/core/src/services/cluster.service.ts:323

Fail an attempt that does not answer within leaseDuration - renewInterval

Type Parameters

R

R

Parameters

attempt

Promise<R>

the attempt

Returns

Promise<R>

its result