@nats-io/services 3.0.0-2

package/build/src/serviceclient.ts

@@ -0,0 +1,106 @@
+/*
+ * Copyright 2022-2024 The NATS Authors
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import {
+  Empty,
+  JSONCodec,
+  QueuedIteratorImpl,
+  RequestStrategy,
+} from "@nats-io/nats-core/internal";
+
+import type {
+  NatsConnection,
+  QueuedIterator,
+  RequestManyOptions,
+} from "@nats-io/nats-core/internal";
+
+import { ServiceImpl } from "./service";
+import { ServiceVerb } from "./types";
+
+import type {
+  ServiceClient,
+  ServiceIdentity,
+  ServiceInfo,
+  ServiceStats,
+} from "./types";
+
+export class ServiceClientImpl implements ServiceClient {
+  nc: NatsConnection;
+  prefix: string | undefined;
+  opts: RequestManyOptions;
+  constructor(
+    nc: NatsConnection,
+    opts: RequestManyOptions = {
+      strategy: RequestStrategy.JitterTimer,
+      maxWait: 2000,
+    },
+    prefix?: string,
+  ) {
+    this.nc = nc;
+    this.prefix = prefix;
+    this.opts = opts;
+  }
+
+  ping(
+    name = "",
+    id = "",
+  ): Promise<QueuedIterator<ServiceIdentity>> {
+    return this.q<ServiceIdentity>(ServiceVerb.PING, name, id);
+  }
+
+  stats(
+    name = "",
+    id = "",
+  ): Promise<QueuedIterator<ServiceStats>> {
+    return this.q<ServiceStats>(ServiceVerb.STATS, name, id);
+  }
+
+  info(
+    name = "",
+    id = "",
+  ): Promise<QueuedIterator<ServiceInfo>> {
+    return this.q<ServiceInfo>(ServiceVerb.INFO, name, id);
+  }
+
+  async q<T>(
+    v: ServiceVerb,
+    name = "",
+    id = "",
+  ): Promise<QueuedIterator<T>> {
+    const iter = new QueuedIteratorImpl<T>();
+    const jc = JSONCodec<T>();
+    const subj = ServiceImpl.controlSubject(v, name, id, this.prefix);
+    const responses = await this.nc.requestMany(subj, Empty, this.opts);
+    (async () => {
+      for await (const m of responses) {
+        try {
+          const s = jc.decode(m.data);
+          iter.push(s);
+        } catch (err) {
+          // @ts-ignore: pushing fn
+          iter.push(() => {
+            iter.stop(err);
+          });
+        }
+      }
+      //@ts-ignore: push a fn
+      iter.push(() => {
+        iter.stop();
+      });
+    })().catch((err) => {
+      iter.stop(err);
+    });
+    return iter;
+  }
+}

package/build/src/types.ts

@@ -0,0 +1,300 @@
+import type {
+  Msg,
+  Nanos,
+  NatsError,
+  PublishOptions,
+  QueuedIterator,
+} from "@nats-io/nats-core";
+
+export interface ServiceMsg extends Msg {
+  respondError(
+    code: number,
+    description: string,
+    data?: Uint8Array,
+    opts?: PublishOptions,
+  ): boolean;
+}
+
+export type ServiceHandler = (err: NatsError | null, msg: ServiceMsg) => void;
+/**
+ * A service Endpoint
+ */
+export type Endpoint = {
+  /**
+   * Subject where the endpoint listens
+   */
+  subject: string;
+  /**
+   * An optional handler - if not set the service is an iterator
+   * @param err
+   * @param msg
+   */
+  handler?: ServiceHandler;
+  /**
+   * Optional metadata about the endpoint
+   */
+  metadata?: Record<string, string>;
+  /**
+   * Optional queue group to run this particular endpoint in. The service's configuration
+   * queue configuration will be used. See {@link ServiceConfig}.
+   */
+  queue?: string;
+};
+export type EndpointOptions = Partial<Endpoint>;
+export type EndpointInfo = {
+  name: string;
+  subject: string;
+  metadata?: Record<string, string>;
+  queue_group?: string;
+};
+
+export interface ServiceGroup {
+  /**
+   * The name of the endpoint must be a simple subject token with no wildcards
+   * @param name
+   * @param opts is either a handler or a more complex options which allows a
+   *  subject, handler, and/or schema
+   */
+  addEndpoint(
+    name: string,
+    opts?: ServiceHandler | EndpointOptions,
+  ): QueuedIterator<ServiceMsg>;
+
+  /**
+   * A group is a subject prefix from which endpoints can be added.
+   * Can be empty to allow for prefixes or tokens that are set at runtime
+   * without requiring editing of the service.
+   * Note that an optional queue can be specified, all endpoints added to
+   * the group, will use the specified queue unless the endpoint overrides it.
+   * see {@link EndpointOptions} and {@link ServiceConfig}.
+   * @param subject
+   * @param queue
+   */
+  addGroup(subject?: string, queue?: string): ServiceGroup;
+}
+
+export type ServiceMetadata = {
+  metadata?: Record<string, string>;
+};
+
+export enum ServiceResponseType {
+  STATS = "io.nats.micro.v1.stats_response",
+  INFO = "io.nats.micro.v1.info_response",
+  PING = "io.nats.micro.v1.ping_response",
+}
+
+export interface ServiceResponse {
+  /**
+   * Response type schema
+   */
+  type: ServiceResponseType;
+}
+
+export type ServiceIdentity = ServiceResponse & ServiceMetadata & {
+  /**
+   * The kind of the service reporting the stats
+   */
+  name: string;
+  /**
+   * The unique ID of the service reporting the stats
+   */
+  id: string;
+  /**
+   * A version for the service
+   */
+  version: string;
+};
+export type NamedEndpointStats = {
+  /**
+   * The name of the endpoint
+   */
+  name: string;
+  /**
+   * The subject the endpoint is listening on
+   */
+  subject: string;
+  /**
+   * The number of requests received by the endpoint
+   */
+  num_requests: number;
+  /**
+   * Number of errors that the endpoint has raised
+   */
+  num_errors: number;
+  /**
+   * If set, the last error triggered by the endpoint
+   */
+  last_error?: string;
+  /**
+   * A field that can be customized with any data as returned by stats handler see {@link ServiceConfig}
+   */
+  data?: unknown;
+  /**
+   * Total processing_time for the service
+   */
+  processing_time: Nanos;
+  /**
+   * Average processing_time is the total processing_time divided by the num_requests
+   */
+  average_processing_time: Nanos;
+  /**
+   * The queue group the endpoint is listening on
+   */
+  queue_group?: string;
+};
+/**
+ * Statistics for an endpoint
+ */
+export type EndpointStats = ServiceIdentity & {
+  endpoints?: NamedEndpointStats[];
+  /**
+   * ISO Date string when the service started
+   */
+  started: string;
+};
+export type ServiceInfo = ServiceIdentity & {
+  /**
+   * Description for the service
+   */
+  description: string;
+  /**
+   * Service metadata
+   */
+  metadata?: Record<string, string>;
+  /**
+   * Information about the Endpoints
+   */
+  endpoints: EndpointInfo[];
+};
+export type ServiceConfig = {
+  /**
+   * A type for a service
+   */
+  name: string;
+  /**
+   * A version identifier for the service
+   */
+  version: string;
+  /**
+   * Description for the service
+   */
+  description?: string;
+  /**
+   * A customized handler for the stats of an endpoint. The
+   * data returned by the endpoint will be serialized as is
+   * @param endpoint
+   */
+  statsHandler?: (
+    endpoint: Endpoint,
+  ) => Promise<unknown | null>;
+
+  /**
+   * Optional metadata about the service
+   */
+  metadata?: Record<string, string>;
+  /**
+   * Optional queue group to run the service in. By default,
+   * then queue name is "q". Note that this configuration will
+   * be the default for all endpoints and groups.
+   */
+  queue?: string;
+};
+/**
+ * The stats of a service
+ */
+export type ServiceStats = ServiceIdentity & EndpointStats;
+
+export interface Service extends ServiceGroup {
+  /**
+   * A promise that gets resolved to null or Error once the service ends.
+   * If an error, then service exited because of an error.
+   */
+  stopped: Promise<null | Error>;
+  /**
+   * True if the service is stopped
+   */
+  // FIXME: this would be better as stop - but the queued iterator may be an issue perhaps call it `isStopped`
+  isStopped: boolean;
+
+  /**
+   * Returns the stats for the service.
+   */
+  stats(): Promise<ServiceStats>;
+
+  /**
+   * Returns a service info for the service
+   */
+  info(): ServiceInfo;
+
+  /**
+   * Returns the identity used by this service
+   */
+  ping(): ServiceIdentity;
+
+  /**
+   * Resets all the stats
+   */
+  reset(): void;
+
+  /**
+   * Stop the service returning a promise once the service completes.
+   * If the service was stopped due to an error, that promise resolves to
+   * the specified error
+   */
+  stop(err?: Error): Promise<null | Error>;
+}
+
+export const ServiceErrorHeader = "Nats-Service-Error";
+export const ServiceErrorCodeHeader = "Nats-Service-Error-Code";
+
+export class ServiceError extends Error {
+  code: number;
+
+  constructor(code: number, message: string) {
+    super(message);
+    this.code = code;
+  }
+
+  static isServiceError(msg: Msg): boolean {
+    return ServiceError.toServiceError(msg) !== null;
+  }
+
+  static toServiceError(msg: Msg): ServiceError | null {
+    const scode = msg?.headers?.get(ServiceErrorCodeHeader) || "";
+    if (scode !== "") {
+      const code = parseInt(scode) || 400;
+      const description = msg?.headers?.get(ServiceErrorHeader) || "";
+      return new ServiceError(code, description.length ? description : scode);
+    }
+    return null;
+  }
+}
+
+export enum ServiceVerb {
+  PING = "PING",
+  STATS = "STATS",
+  INFO = "INFO",
+}
+
+export interface ServiceClient {
+  /**
+   * Pings services
+   * @param name - optional
+   * @param id - optional
+   */
+  ping(name?: string, id?: string): Promise<QueuedIterator<ServiceIdentity>>;
+
+  /**
+   * Requests all the stats from services
+   * @param name
+   * @param id
+   */
+  stats(name?: string, id?: string): Promise<QueuedIterator<ServiceStats>>;
+
+  /**
+   * Requests info from services
+   * @param name
+   * @param id
+   */
+  info(name?: string, id?: string): Promise<QueuedIterator<ServiceInfo>>;
+}

package/lib/internal_mod.d.ts

@@ -0,0 +1,10 @@
+import type { NatsConnection, RequestManyOptions } from "@nats-io/nats-core";
+import type { Service, ServiceClient, ServiceConfig } from "./types";
+export type { Endpoint, EndpointInfo, EndpointOptions, EndpointStats, NamedEndpointStats, Service, ServiceClient, ServiceConfig, ServiceGroup, ServiceHandler, ServiceIdentity, ServiceInfo, ServiceMetadata, ServiceMsg, ServiceResponse, ServiceStats, } from "./types";
+export { ServiceError, ServiceErrorCodeHeader, ServiceErrorHeader, ServiceResponseType, ServiceVerb, } from "./types";
+export declare class Svc {
+    nc: NatsConnection;
+    constructor(nc: NatsConnection);
+    add(config: ServiceConfig): Promise<Service>;
+    client(opts?: RequestManyOptions, prefix?: string): ServiceClient;
+}

package/lib/internal_mod.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Svc = exports.ServiceVerb = exports.ServiceResponseType = exports.ServiceErrorHeader = exports.ServiceErrorCodeHeader = exports.ServiceError = void 0;
+const service_1 = require("./service");
+const serviceclient_1 = require("./serviceclient");
+var types_1 = require("./types");
+Object.defineProperty(exports, "ServiceError", { enumerable: true, get: function () { return types_1.ServiceError; } });
+Object.defineProperty(exports, "ServiceErrorCodeHeader", { enumerable: true, get: function () { return types_1.ServiceErrorCodeHeader; } });
+Object.defineProperty(exports, "ServiceErrorHeader", { enumerable: true, get: function () { return types_1.ServiceErrorHeader; } });
+Object.defineProperty(exports, "ServiceResponseType", { enumerable: true, get: function () { return types_1.ServiceResponseType; } });
+Object.defineProperty(exports, "ServiceVerb", { enumerable: true, get: function () { return types_1.ServiceVerb; } });
+class Svc {
+    nc;
+    constructor(nc) {
+        this.nc = nc;
+    }
+    add(config) {
+        try {
+            const s = new service_1.ServiceImpl(this.nc, config);
+            return s.start();
+        }
+        catch (err) {
+            return Promise.reject(err);
+        }
+    }
+    client(opts, prefix) {
+        return new serviceclient_1.ServiceClientImpl(this.nc, opts, prefix);
+    }
+}
+exports.Svc = Svc;
+//# sourceMappingURL=internal_mod.js.map

package/lib/internal_mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal_mod.js","sourceRoot":"","sources":["../build/src/internal_mod.ts"],"names":[],"mappings":";;;AACA,uCAAwC;AACxC,mDAAoD;AAsBpD,iCAMiB;AALf,qGAAA,YAAY,OAAA;AACZ,+GAAA,sBAAsB,OAAA;AACtB,2GAAA,kBAAkB,OAAA;AAClB,4GAAA,mBAAmB,OAAA;AACnB,oGAAA,WAAW,OAAA;AAGb,MAAa,GAAG;IACd,EAAE,CAAiB;IAEnB,YAAY,EAAkB;QAC5B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED,GAAG,CAAC,MAAqB;QACvB,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,IAAI,qBAAW,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;YAC3C,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,MAAM,CAAC,IAAyB,EAAE,MAAe;QAC/C,OAAO,IAAI,iCAAiB,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACtD,CAAC;CACF;AAnBD,kBAmBC"}

package/lib/mod.d.ts

@@ -0,0 +1,2 @@
+export type { Endpoint, EndpointInfo, EndpointOptions, EndpointStats, NamedEndpointStats, Service, ServiceClient, ServiceConfig, ServiceGroup, ServiceHandler, ServiceIdentity, ServiceInfo, ServiceMetadata, ServiceMsg, ServiceResponse, ServiceStats, } from "./internal_mod";
+export { ServiceError, ServiceErrorCodeHeader, ServiceErrorHeader, ServiceResponseType, ServiceVerb, Svc, } from "./internal_mod";

package/lib/mod.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Svc = exports.ServiceVerb = exports.ServiceResponseType = exports.ServiceErrorHeader = exports.ServiceErrorCodeHeader = exports.ServiceError = void 0;
+var internal_mod_1 = require("./internal_mod");
+Object.defineProperty(exports, "ServiceError", { enumerable: true, get: function () { return internal_mod_1.ServiceError; } });
+Object.defineProperty(exports, "ServiceErrorCodeHeader", { enumerable: true, get: function () { return internal_mod_1.ServiceErrorCodeHeader; } });
+Object.defineProperty(exports, "ServiceErrorHeader", { enumerable: true, get: function () { return internal_mod_1.ServiceErrorHeader; } });
+Object.defineProperty(exports, "ServiceResponseType", { enumerable: true, get: function () { return internal_mod_1.ServiceResponseType; } });
+Object.defineProperty(exports, "ServiceVerb", { enumerable: true, get: function () { return internal_mod_1.ServiceVerb; } });
+Object.defineProperty(exports, "Svc", { enumerable: true, get: function () { return internal_mod_1.Svc; } });
+//# sourceMappingURL=mod.js.map

package/lib/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../build/src/mod.ts"],"names":[],"mappings":";;;AAmBA,+CAOwB;AANtB,4GAAA,YAAY,OAAA;AACZ,sHAAA,sBAAsB,OAAA;AACtB,kHAAA,kBAAkB,OAAA;AAClB,mHAAA,mBAAmB,OAAA;AACnB,2GAAA,WAAW,OAAA;AACX,mGAAA,GAAG,OAAA"}

package/lib/service.d.ts

@@ -0,0 +1,105 @@
+import type { Deferred, Msg, MsgHdrs, Nanos, NatsConnection, NatsError, Payload, PublishOptions, QueuedIterator, ReviverFn, Sub } from "@nats-io/nats-core/internal";
+import { ServiceVerb } from "./types";
+import type { Endpoint, EndpointInfo, EndpointOptions, NamedEndpointStats, Service, ServiceConfig, ServiceGroup, ServiceHandler, ServiceIdentity, ServiceInfo, ServiceMsg, ServiceStats } from "./types";
+/**
+ * Services have common backplane subject pattern:
+ *
+ * `$SRV.PING|STATS|INFO` - pings or retrieves status for all services
+ * `$SRV.PING|STATS|INFO.<name>` - pings or retrieves status for all services having the specified name
+ * `$SRV.PING|STATS|INFO.<name>.<id>` - pings or retrieves status of a particular service
+ *
+ * Note that <name> and <id> are upper-cased.
+ */
+export declare const ServiceApiPrefix = "$SRV";
+export declare class ServiceMsgImpl implements ServiceMsg {
+    msg: Msg;
+    constructor(msg: Msg);
+    get data(): Uint8Array;
+    get sid(): number;
+    get subject(): string;
+    get reply(): string;
+    get headers(): MsgHdrs | undefined;
+    respond(data?: Payload, opts?: PublishOptions): boolean;
+    respondError(code: number, description: string, data?: Uint8Array, opts?: PublishOptions): boolean;
+    json<T = unknown>(reviver?: ReviverFn): T;
+    string(): string;
+}
+export declare class ServiceGroupImpl implements ServiceGroup {
+    subject: string;
+    queue: string;
+    srv: ServiceImpl;
+    constructor(parent: ServiceGroup, name?: string, queue?: string);
+    calcSubject(root: string, name?: string): string;
+    addEndpoint(name?: string, opts?: ServiceHandler | EndpointOptions): QueuedIterator<ServiceMsg>;
+    addGroup(name?: string, queue?: string): ServiceGroup;
+}
+type NamedEndpoint = {
+    name: string;
+} & Endpoint;
+type ServiceSubscription<T = unknown> = NamedEndpoint & {
+    internal: boolean;
+    sub: Sub<T>;
+    qi?: QueuedIterator<T>;
+    stats: NamedEndpointStatsImpl;
+    metadata?: Record<string, string>;
+};
+export declare class ServiceImpl implements Service {
+    nc: NatsConnection;
+    _id: string;
+    config: ServiceConfig;
+    handlers: ServiceSubscription[];
+    internal: ServiceSubscription[];
+    _stopped: boolean;
+    _done: Deferred<Error | null>;
+    started: string;
+    /**
+     * @param verb
+     * @param name
+     * @param id
+     * @param prefix - this is only supplied by tooling when building control subject that crosses an account
+     */
+    static controlSubject(verb: ServiceVerb, name?: string, id?: string, prefix?: string): string;
+    constructor(nc: NatsConnection, config?: ServiceConfig);
+    get subjects(): string[];
+    get id(): string;
+    get name(): string;
+    get description(): string;
+    get version(): string;
+    get metadata(): Record<string, string> | undefined;
+    errorToHeader(err: Error): MsgHdrs;
+    setupHandler(h: NamedEndpoint, internal?: boolean): ServiceSubscription;
+    info(): ServiceInfo;
+    endpoints(): EndpointInfo[];
+    stats(): Promise<ServiceStats>;
+    addInternalHandler(verb: ServiceVerb, handler: (err: NatsError | null, msg: Msg) => Promise<void>): void;
+    _doAddInternalHandler(name: string, verb: ServiceVerb, handler: (err: NatsError | null, msg: Msg) => Promise<void>, kind?: string, id?: string): void;
+    start(): Promise<Service>;
+    close(err?: Error): Promise<null | Error>;
+    get stopped(): Promise<null | Error>;
+    get isStopped(): boolean;
+    stop(err?: Error): Promise<null | Error>;
+    ping(): ServiceIdentity;
+    reset(): void;
+    addGroup(name: string, queue?: string): ServiceGroup;
+    addEndpoint(name: string, handler?: ServiceHandler | EndpointOptions): QueuedIterator<ServiceMsg>;
+    _addEndpoint(e: NamedEndpoint): QueuedIterator<ServiceMsg>;
+}
+declare class NamedEndpointStatsImpl implements NamedEndpointStats {
+    name: string;
+    subject: string;
+    average_processing_time: Nanos;
+    num_requests: number;
+    processing_time: Nanos;
+    num_errors: number;
+    last_error?: string;
+    data?: unknown;
+    metadata?: Record<string, string>;
+    queue: string;
+    constructor(name: string, subject: string, queue?: string);
+    reset(qi?: QueuedIterator<unknown>): void;
+    countLatency(start: number): void;
+    countError(err: Error): void;
+    _stats(): NamedEndpointStats;
+    stats(qi?: QueuedIterator<unknown>): NamedEndpointStats;
+}
+export {};