Skip to content

Latest commit

 

History

History
382 lines (271 loc) · 9.11 KB

API.md

File metadata and controls

382 lines (271 loc) · 9.11 KB

API

Links: API, Interfaces, Classes, Types

Interfaces

Interface: EngineConfig

Configuration options that map to Engine constructor parameters.

export interface EngineConfig {
    chainTracker?: ChainTracker | "scripts only";
    shipTrackers?: string[];
    slapTrackers?: string[];
    broadcaster?: Broadcaster;
    advertiser?: Advertiser;
    syncConfiguration?: Record<string, string[] | "SHIP" | false>;
    logTime?: boolean;
    logPrefix?: string;
    throwOnBroadcastFailure?: boolean;
    overlayBroadcastFacilitator?: OverlayBroadcastFacilitator;
}

Links: API, Interfaces, Classes, Types

Classes

Class: OverlayExpress

OverlayExpress class provides an Express-based server for hosting Overlay Services. It allows configuration of various components like databases, topic managers, and lookup services. It encapsulates an Express application and provides methods to start the server.

export default class OverlayExpress {
    app: express.Application;
    port: number = 3000;
    logger: typeof console = console;
    knex: Knex.Knex | undefined = undefined;
    migrationsToRun: Array<Migration> = [];
    mongoDb: Db | undefined = undefined;
    network: "main" | "test" = "main";
    chainTracker: ChainTracker | "scripts only" = new WhatsOnChain(this.network);
    engine: Engine | undefined = undefined;
    managers: Record<string, TopicManager> = {};
    services: Record<string, LookupService> = {};
    enableGASPSync: boolean = true;
    arcApiKey: string | undefined = undefined;
    verboseRequestLogging: boolean = false;
    webUIConfig: UIConfig = {};
    engineConfig: EngineConfig = {};
    constructor(public name: string, public privateKey: string, public hostingURL: string, adminToken?: string) 
    getAdminToken(): string 
    configurePort(port: number): void 
    configureWebUI(config: UIConfig): void 
    configureLogger(logger: typeof console): void 
    configureNetwork(network: "main" | "test"): void 
    configureChainTracker(chainTracker: ChainTracker | "scripts only" = new WhatsOnChain(this.network)): void 
    configureArcApiKey(apiKey: string): void 
    configureEnableGASPSync(enable: boolean): void 
    configureVerboseRequestLogging(enable: boolean): void 
    async configureKnex(config: Knex.Knex.Config | string): Promise<void> 
    async configureMongo(connectionString: string): Promise<void> 
    configureTopicManager(name: string, manager: TopicManager): void 
    configureLookupService(name: string, service: LookupService): void 
    configureLookupServiceWithKnex(name: string, serviceFactory: (knex: Knex.Knex) => {
        service: LookupService;
        migrations: Array<Migration>;
    }): void 
    configureLookupServiceWithMongo(name: string, serviceFactory: (mongoDb: Db) => LookupService): void 
    configureEngineParams(params: EngineConfig): void 
    async configureEngine(autoConfigureShipSlap = true): Promise<void> 
    async start() 
}

See also: EngineConfig, UIConfig

Class OverlayExpress Details

Constructor

Constructs an instance of OverlayExpress.

constructor(public name: string, public privateKey: string, public hostingURL: string, adminToken?: string)

Argument Details

  • name
    • The name of the service
  • privateKey
    • Private key used for signing advertisements
  • hostingURL
    • The public URL where this service is hosted
  • adminToken
    • Optional. An administrative Bearer token used to protect admin routes. If not provided, a random token will be generated at runtime.

Method configureArcApiKey

Configures the ARC API key.

configureArcApiKey(apiKey: string): void

Argument Details

  • apiKey
    • The ARC API key

Method configureChainTracker

Configures the ChainTracker to be used. If 'scripts only' is used, it implies no full SPV chain tracking in the Engine.

configureChainTracker(chainTracker: ChainTracker | "scripts only" = new WhatsOnChain(this.network)): void

Argument Details

  • chainTracker
    • An instance of ChainTracker or 'scripts only'

Method configureEnableGASPSync

Enables or disables GASP synchronization (high-level setting). This is a broad toggle that can be overridden or customized through syncConfiguration.

configureEnableGASPSync(enable: boolean): void

Argument Details

  • enable
    • true to enable, false to disable

Method configureEngine

Configures the Overlay Engine itself. By default, auto-configures SHIP and SLAP unless autoConfigureShipSlap = false Then it merges in any advanced engine config from this.engineConfig.

async configureEngine(autoConfigureShipSlap = true): Promise<void>

Argument Details

  • autoConfigureShipSlap
    • Whether to auto-configure SHIP and SLAP services (default: true)

Method configureEngineParams

Advanced configuration method for setting or overriding any Engine constructor parameters via an EngineConfig object.

Example usage: configureEngineParams({ logTime: true, throwOnBroadcastFailure: true, overlayBroadcastFacilitator: new MyCustomFacilitator() })

These fields will be respected when we finally build/configure the Engine in the configureEngine() method below.

configureEngineParams(params: EngineConfig): void

See also: EngineConfig

Method configureKnex

Configure Knex (SQL) database connection.

async configureKnex(config: Knex.Knex.Config | string): Promise<void>

Argument Details

  • config
    • Knex configuration object, or MySQL connection string (e.g. mysql://overlayAdmin:overlay123@mysql:3306/overlay).

Method configureLogger

Configures the logger to be used by the server.

configureLogger(logger: typeof console): void

Argument Details

  • logger
    • A logger object (e.g., console)

Method configureLookupService

Configures a Lookup Service.

configureLookupService(name: string, service: LookupService): void

Argument Details

  • name
    • The name of the Lookup Service
  • service
    • An instance of LookupService

Method configureLookupServiceWithKnex

Configures a Lookup Service using Knex (SQL) database.

configureLookupServiceWithKnex(name: string, serviceFactory: (knex: Knex.Knex) => {
    service: LookupService;
    migrations: Array<Migration>;
}): void

Argument Details

  • name
    • The name of the Lookup Service
  • serviceFactory
    • A factory function that creates a LookupService instance using Knex

Method configureLookupServiceWithMongo

Configures a Lookup Service using MongoDB.

configureLookupServiceWithMongo(name: string, serviceFactory: (mongoDb: Db) => LookupService): void

Argument Details

  • name
    • The name of the Lookup Service
  • serviceFactory
    • A factory function that creates a LookupService instance using MongoDB

Method configureMongo

Configures the MongoDB database connection.

async configureMongo(connectionString: string): Promise<void>

Argument Details

  • connectionString
    • MongoDB connection string

Method configureNetwork

Configures the BSV Blockchain network to be used ('main' or 'test'). By default, it re-initializes chainTracker as a WhatsOnChain for that network.

configureNetwork(network: "main" | "test"): void

Argument Details

  • network
    • The network ('main' or 'test')

Method configurePort

Configures the port on which the server will listen.

configurePort(port: number): void

Argument Details

  • port
    • The port number

Method configureTopicManager

Configures a Topic Manager.

configureTopicManager(name: string, manager: TopicManager): void

Argument Details

  • name
    • The name of the Topic Manager
  • manager
    • An instance of TopicManager

Method configureVerboseRequestLogging

Enables or disables verbose request logging.

configureVerboseRequestLogging(enable: boolean): void

Argument Details

  • enable
    • true to enable, false to disable

Method configureWebUI

Configures the web user interface

configureWebUI(config: UIConfig): void

See also: UIConfig

Argument Details

  • config
    • Web UI configuration options

Method getAdminToken

Returns the current admin token in case you need to programmatically retrieve or display it.

getAdminToken(): string

Method start

Starts the Express server. Sets up routes and begins listening on the configured port.

async start()

Links: API, Interfaces, Classes, Types

Types

Type: UIConfig

export type UIConfig = {
    faviconUrl?: string;
    backgroundColor?: string;
    primaryColor?: string;
    secondaryColor?: string;
    fontFamily?: string;
    headingFontFamily?: string;
    additionalStyles?: string;
    sectionBackgroundColor?: string;
    linkColor?: string;
    hoverColor?: string;
    borderColor?: string;
}

Links: API, Interfaces, Classes, Types