Interfaces

Interfaces describe how an entity is exposed. They carry metadata about protocol, port, and connection details.

Base class

All interfaces extend EntityInterface:

abstract class EntityInterface {
  get protocol(): InterfaceProtocol  // "http" | "tcp" | "ws" | "grpc"
  get port(): number | undefined
  get host(): string                 // default: "localhost"
  abstract getConnectionString(): string
  abstract isReady(): Promise<boolean>
}

APIInterface

HTTP interface for REST/API services.

import { APIInterface } from "sigil";

new APIInterface(port: number)

Property	Value
protocol	"http"
getConnectionString()	"http://localhost:<port>"
isReady()	GET http://localhost:<port>/health returns 2xx

Usage:

env.add(
  new Service("backend", config, [new APIInterface(8000)])
);

BrowserInterface

WebSocket interface for browser-based services.

import { BrowserInterface } from "sigil";

new BrowserInterface(port?: number)

Property	Value
protocol	"ws"
getConnectionString()	WebSocket endpoint (set internally)
isReady()	Returns true when endpoint is set

Usage:

env.add(
  new Service("frontend", config, [new BrowserInterface(3000)])
);

PostgresInterface

TCP interface for PostgreSQL connections. Created automatically by the Postgres entity — you typically don’t construct this directly.

new PostgresInterface(port: number, database: string, username: string, password: string)

Property	Value
protocol	"tcp"
getConnectionString()	"postgresql://<user>:<pass>@<host>:<port>/<db>"

Access via the Postgres entity:

const db = env.add(new Postgres("db", { database: "myapp" }));
db.connectionString;  // "postgresql://postgres:postgres@localhost:5432/myapp"
db.pgInterface;       // the PostgresInterface instance

Attaching interfaces to services

The Service constructor accepts an optional array of interfaces:

new Service(name, config, interfaces?)

Interfaces on a Service are metadata — they describe what the service exposes but don’t affect the service’s behavior. They’re used for status reporting and will be used for future features like API discovery.

// A service that exposes both an API and a web UI
env.add(
  new Service("app", config, [
    new APIInterface(8000),
    new BrowserInterface(3000),
  ])
);