service-discovery-plugin/src/index.ts

Examples

Example 1

import { createApplication } from '@setu-ts/kernel';
import { RuntimePlugin } from '@setu-ts/runtime';
import { ServiceDiscoveryPlugin } from '@setu-ts/service-discovery-plugin';
import { CAPABILITIES, type IServiceDiscovery } from '@setu-ts/common';

const app = createApplication({
  plugins: [
    RuntimePlugin(),
    ServiceDiscoveryPlugin({
      provider: 'consul',
      address: 'http://127.0.0.1:8500',
    }),
  ],
});

await app.start({ port: 3000 });

const discovery = app.services.get<IServiceDiscovery>(
  CAPABILITIES.SERVICE_DISCOVERY,
);
const url = await discovery.resolveUrl('billing', '/invoices');

Classes

ConsulProvider(

options: ConsulProviderOptions,

http: IDiscoveryHttp,

runtime: IRuntimeServices

)

Reads and registers against a Consul agent.

deregisterSelf(registration: SelfRegistration): Promise<void>
Removes this instance from the agent.
headers(): Record<string, string>
Headers every request carries; the ACL header is omitted when unset.
healthUrl(
serviceName: string,
index?: number
): string
Builds the health-read URL.
isHealthy(): Promise<boolean>
M70c: probes the agent's leader endpoint — GET /v1/status/leader — through the existing IDiscoveryHttp seam. 2xx means the agent is reachable; any other status or a transport failure means it is not.
kind: string
Backend id.
mapEntries(
body: unknown,
serviceName: string
): readonly ServiceInstance[]
Maps a health response body onto instances.
registerSelf(registration: SelfRegistration): Promise<void>
Advertises this instance to the agent.
resolve(serviceName: string): Promise<readonly ServiceInstance[]>
Reads the current instance list for a service.
selfId(registration: SelfRegistration): string
The instance id used for both register and deregister.
watch(
serviceName: string,
listener: (instances: readonly ServiceInstance[]) => void
): Promise<Unsubscribe>
Subscribes to instance-list changes.

DiscoveryUnavailableError(

message: string,

options?: ErrorOptions

)

Discovery could not answer.

name: string
Discriminating name for instanceof-free checks.

DnsProvider(

resolver: IDnsResolver,

runtime: IRuntimeServices,

options: DnsProviderOptions

)

Resolves services through DNS.

domainFor(serviceName: string): string
Substitutes the service name into the configured template.
kind: string
Backend id.
resolve(serviceName: string): Promise<readonly ServiceInstance[]>
Reads the current instance list for a service.
watch(
serviceName: string,
listener: (instances: readonly ServiceInstance[]) => void
): Promise<Unsubscribe>
Polls at watchIntervalMs, firing only when the instance list changed.

KubernetesProvider(

options: KubernetesProviderOptions,

http: IDiscoveryHttp,

runtime: IRuntimeServices

)

Reads EndpointSlices for a service.

authHeader(): Promise<string>
Resolves the bearer token, reading the projected file when no explicit token was configured.
isHealthy(): Promise<boolean>
M70c: probes the API server with a limit=1 EndpointSlice LIST through the existing seam. This is the probe that makes X10-3 visible: an UnknownIssuer TLS rejection surfaces here as down. 2xx means the API is reachable.
kind: string
Backend id.
listUrl(
serviceName: string,
extra?: Readonly<Record<string, string>>
): string
Builds the EndpointSlice list URL for a service.
mapSlices(
body: unknown,
serviceName: string
): readonly ServiceInstance[]
Maps an EndpointSlice list onto instances.
resolve(serviceName: string): Promise<readonly ServiceInstance[]>
Reads the current instance list for a service.
watch(
serviceName: string,
listener: (instances: readonly ServiceInstance[]) => void
): Promise<Unsubscribe>
Subscribes to instance-list changes.

SelfRegistrationNotSupportedError(provider: string)

selfRegistration was configured against a provider that cannot register.

name: string
Discriminating name for instanceof-free checks.

StaticProvider(

services: Readonly<Record<string, readonly StaticServiceDefinition[]>>,

runtime: IRuntimeServices

)

Serves a configured instance list.

isHealthy(): Promise<boolean>
M70c: a static map is in memory and cannot be unreachable, so it is always reachable (M47).
kind: string
Backend id.
resolve(serviceName: string): Promise<readonly ServiceInstance[]>
Reads the current instance list for a service.
watch(
serviceName: string,
listener: (instances: readonly ServiceInstance[]) => void
): Promise<Unsubscribe>
Fires once with the configured list and never again.

Functions

createDefaultDiscoveryHttp(fetchImpl?: fetch): IDiscoveryHttp

Creates the default HTTP seam.

ServiceDiscoveryPlugin(options: ServiceDiscoveryPluginOptions): IPlugin

Creates the service discovery plugin.

Interfaces

ADnsDiscoveryOptions

The 'dns' arm in address mode — A/AAAA records carry no port.

mode: "a"
Query A/AAAA records.
port: number
Port every resolved address is reached on.

ConsulDiscoveryOptions

The 'consul' arm.

address: string
Base URL of the Consul agent, e.g. http://127.0.0.1:8500.
datacenter: string
Datacenter, sent as ?dc=.
http: IDiscoveryHttp
Overrides the default fetch-backed HTTP seam.
provider: "consul"
Discriminant.
secure: boolean
Whether resolved instances speak TLS — Consul carries no scheme.
token: string
ACL token, sent as X-Consul-Token.
waitSeconds: number
Blocking-query wait, in seconds. Default 30, clamped to Consul's documented maximum of 600.

ConsulProviderOptions

Constructor options.

address: string
Base URL of the Consul agent.
datacenter: string
Datacenter, sent as ?dc=.
secure: boolean
Whether resolved instances speak TLS.
token: string
ACL token, sent as X-Consul-Token.
waitSeconds: number
Blocking-query wait, in seconds.

CustomDiscoveryOptions

The 'custom' arm — the application's own backend.

discovery: DiscoveryProvider
The provider, used as supplied.
provider: "custom"
Discriminant.

DiscoveryHttpResponse

A buffered HTTP response, as IDiscoveryHttp.request returns it.

headers: Headers
Response headers.
ok: boolean
Whether the status is 2xx.
status: number
HTTP status code.
text: string
Response body, read to completion as text.

DiscoveryHttpStream

A streaming HTTP response, as IDiscoveryHttp.stream returns it.

body: ReadableStream<Uint8Array> | null
The response body, or null when the response carries none.
headers: Headers
Response headers.
ok: boolean
Whether the status is 2xx.
status: number
HTTP status code.

DiscoveryProvider

A discovery backend.

deregisterSelf(registration: SelfRegistration): Promise<void>
Removes this application instance from the backend.
isHealthy(): Promise<boolean>
M70c: reports whether the discovery backend is reachable right now, for the plugin's health indicator.
kind: string
Backend id, surfaced by the health indicator.
registerSelf(registration: SelfRegistration): Promise<void>
Registers this application instance with the backend.
resolve(serviceName: string): Promise<readonly ServiceInstance[]>
Reads the current instance list for a service.
watch(
serviceName: string,
listener: (instances: readonly ServiceInstance[]) => void
): Promise<Unsubscribe>
Subscribes to instance-list changes.

EjectionOptions

Outlier-ejection tuning.

durationMs: number
How long an ejection lasts, in milliseconds.
failureThreshold: number
Failures inside the window that eject an instance.
maxEjectionPercent: number
Ceiling on the percentage of a service's instances ejected at once.
windowMs: number
Rolling window, in milliseconds, that failures are counted over.

IDiscoveryHttp

The HTTP surface the Consul and Kubernetes providers need.

request(
url: string,
init?: RequestInit
): Promise<DiscoveryHttpResponse>
Performs a request and reads the whole body.
stream(
url: string,
init?: RequestInit
): Promise<DiscoveryHttpStream>
Performs a request and leaves the body unread.

KubernetesDiscoveryOptions

The 'kubernetes' arm — EndpointSlices read from the API server.

apiServer: string
API server base URL. Defaults to the in-cluster https://$KUBERNETES_SERVICE_HOST:$KUBERNETES_SERVICE_PORT.
http: IDiscoveryHttp
Overrides the default fetch-backed HTTP seam.
namespace: string
Namespace the services live in.
portName: string
Selects the ports[] entry by name when a service exposes several.
provider: "kubernetes"
Discriminant.
secure: boolean
Whether resolved instances speak TLS.
token: string
Bearer token, used verbatim.

KubernetesProviderOptions

Constructor options.

apiServer: string
API server base URL, already resolved from options or the environment.
namespace: string
Namespace the services live in.
portName: string
Selects the ports[] entry by name.
secure: boolean
Whether resolved instances speak TLS.
token: string
Bearer token used verbatim; absent means read the projected token file.

SelfRegistration

What this application advertises about itself.

address: string
Address other applications should reach this instance on.
check: SelfRegistrationCheck
The mandatory health check (defaults applied by resolveOptions).
drainDelayMs: number
Milliseconds to keep serving after deregistering, before draining begins.
id: string
Instance id, unique within the service. Defaults to <name>-<uuid>.
metadata: Readonly<Record<string, string>>
Key/value metadata to attach to the registration.
port: number
Port other applications should reach this instance on.
serviceName: string
Logical service name other applications resolve.
tags: readonly string[]
Labels to attach to the registration.

SelfRegistrationCheck

The health check the backend runs against this instance after registration.

deregisterAfterSeconds: number
Seconds a critical service survives before the backend removes it.
httpPath: string
HTTP path the backend polls, appended to this instance's origin.
intervalSeconds: number
Seconds between checks.