Interface HTTP

HTTP service interface

interface HTTP {
    onRequest: HTTPRequestHandler;
    onWebSocket: WebSocketHandler;
    agent(
        peer: Multiaddr | Multiaddr[] | PeerId,
        options?: AgentOptions,
    ): Agent;
    canHandle(req: WebSocket | Request | IncomingMessage): boolean;
    connect(
        resource: string | URL | Multiaddr | Multiaddr[] | PeerId,
        init?: ConnectInit,
    ): Promise<WebSocket>;
    connectProtocol(
        resource: string | URL | Multiaddr | Multiaddr[] | PeerId,
        protocol: string,
        init?: ConnectInit,
    ): Promise<WebSocket>;
    dispatcher(
        peer: Multiaddr | Multiaddr[] | PeerId,
        options?: Options,
    ): Dispatcher;
    fetch(
        resource: string | URL | Multiaddr | Multiaddr[] | PeerId,
        init?: FetchInit,
    ): Promise<Response>;
    fetchProtocol(
        resource: string | URL | Multiaddr | Multiaddr[] | PeerId,
        protocol: string,
        init?: FetchInit,
    ): Promise<Response>;
    getProtocolMap(): ProtocolMap;
    handle(protocol: string, handler: HTTPRoute<HTTPRequestHandler>): void;
    unhandle(protocol: string): void;
}

Index

Properties

onRequest onWebSocket

Methods

agent canHandle connect connectProtocol dispatcher fetch fetchProtocol getProtocolMap handle unhandle

Properties

onRequest

onRequest: HTTPRequestHandler

Handle an incoming HTTP request

onWebSocket

onWebSocket: WebSocketHandler

Handle an incoming WebSocket

Methods

agent

agent(peer: Multiaddr | Multiaddr[] | PeerId, options?: AgentOptions): Agent
Get a libp2p-enabled Agent for use with node's http module. This method will throw when not running under Node.js or Electron.

All requests using this Agent will be sent to the peer reachable by the peer ID or multiaddr(s) passed as the first argument.
Parameters
- peer: Multiaddr | Multiaddr[] | PeerId
- Optionaloptions: AgentOptions
Returns Agent
- Defined in packages/http/src/index.ts:220

canHandle

canHandle(req: WebSocket | Request | IncomingMessage): boolean
Returns true if there is a handler registered for the incoming Request or WebSocket.

Note - the .url property must be set on the WebSocket for this to work. Not all server-side WebSocket frameworks do this out of the box so the caller may have to add the property.
Parameters
- req: WebSocket | Request | IncomingMessage
Returns boolean
- Defined in packages/http/src/index.ts:269

connect

connect(
resource: string | URL | Multiaddr | Multiaddr[] | PeerId,
init?: ConnectInit,
): Promise<WebSocket>
Open a WebSocket connection to an HTTP server over libp2p.

If the passed resource starts with a / character, it will be interpreted as a Multiaddr, otherwise it will be interpreted as a URL.

URLs can start with the multiaddr: scheme if the global URL class in the runtime environment supports it.
Parameters
- resource: string | URL | Multiaddr | Multiaddr[] | PeerId
- Optionalinit: ConnectInit
Returns Promise<WebSocket>
- Defined in packages/http/src/index.ts:211

connectProtocol

connectProtocol(
    resource: string | URL | Multiaddr | Multiaddr[] | PeerId,
    protocol: string,
    init?: ConnectInit,
): Promise<WebSocket>
Look up the path for the protocol and create a WebSocket connection to the handler.

This is similar in scope to libp2p.dialProtocol.
Parameters
- resource: string | URL | Multiaddr | Multiaddr[] | PeerId
- protocol: string
- Optionalinit: ConnectInit
Returns Promise<WebSocket>
- Defined in packages/http/src/index.ts:244

dispatcher

dispatcher(
peer: Multiaddr | Multiaddr[] | PeerId,
options?: Options,
): Dispatcher
Get a libp2p-enabled Dispatcher for use with the undici module. This method will throw when not running under Node.js or Electron.

All requests using this Agent will be sent to the peer reachable by the peer ID or multiaddr(s) passed as the first argument.
Parameters
- peer: Multiaddr | Multiaddr[] | PeerId
- Optionaloptions: Options
Returns Dispatcher
- Defined in packages/http/src/index.ts:229

fetch

fetch(
resource: string | URL | Multiaddr | Multiaddr[] | PeerId,
init?: FetchInit,
): Promise<Response>
Make a request in a similar way to globalThis.fetch.

If the passed resource is a string, if it starts with a / character it will be interpreted as a Multiaddr, otherwise it will be interpreted as a URL.

URLs can start with the multiaddr: scheme if the global URL class in the runtime environment supports it.
Parameters
- resource: string | URL | Multiaddr | Multiaddr[] | PeerId
- Optionalinit: FetchInit
Returns Promise<Response>
- Defined in packages/http/src/index.ts:200

fetchProtocol

fetchProtocol(
    resource: string | URL | Multiaddr | Multiaddr[] | PeerId,
    protocol: string,
    init?: FetchInit,
): Promise<Response>
Look up the path for the protocol and invoke it with the passed arguments.

This is similar in scope to libp2p.dialProtocol.
Parameters
- resource: string | URL | Multiaddr | Multiaddr[] | PeerId
- protocol: string
- Optionalinit: FetchInit
Returns Promise<Response>
- Defined in packages/http/src/index.ts:236

getProtocolMap

getProtocolMap(): ProtocolMap
Return the protocol->path mappings supported by this server

Returns ProtocolMap
- Defined in packages/http/src/index.ts:259

handle

handle(protocol: string, handler: HTTPRoute<HTTPRequestHandler>): void
Register a listener for a HTTP protocol
Parameters
- protocol: string
- handler: HTTPRoute<HTTPRequestHandler>
Returns void
- Defined in packages/http/src/index.ts:249

unhandle

unhandle(protocol: string): void
Remove a listener for a HTTP protocol
Parameters
- protocol: string
Returns void
- Defined in packages/http/src/index.ts:254