GitHub

API reference for server.

Socket servers (Effect's SocketServer and NodeSocketServer): listen on the socket loop, hand each connection to a handler.

Connections that arrive before run (or between runs) wait in a pending list; run takes them, and every later one, and forks the handler for each in a scope of its own, which closes when run is interrupted. The loop only appends to the list and wakes run: forking happens on the running fiber.

Types

TypeDefinitionDescription
SocketServerErrorReasontype SocketServerErrorReason = SocketServerOpenError | SocketServerUnknownError
Listentype Listen = Callable[[Callable[[], Connection]], Any]

Start listening, making each connection's protocol with the factory.

Classes

Functions

report_unhandled

report_unhandled(cause) -> Effect[None]
ParameterTypeDescription
causeCause[object]

Returns Effect[None]

def report_unhandled(cause: Cause[object]) -> Effect[None]:
    return log_unhandled("Unhandled error in SocketServer", cause)

make

make(port=0, host=None) -> Effect[SocketServerService, SocketServerError, Scope]

A TCP server listening on host:port (port 0: any free port; no host: every interface), closed with the scope.

ParameterTypeDescription
portint = 0
hoststr | None = None

Returns Effect[SocketServerService, SocketServerError, Scope]

def make(
    port: int = 0, host: str | None = None
) -> Effect[SocketServerService, SocketServerError, Scope]:
    """A TCP server listening on ``host:port`` (port 0: any free port; no
    host: every interface), closed with the scope."""
    return _listen(lambda factory: get_loop().create_server(factory, host, port))

make_unix

make_unix(path) -> Effect[SocketServerService, SocketServerError, Scope]

A server listening on the Unix socket at path.

ParameterTypeDescription
pathstr

Returns Effect[SocketServerService, SocketServerError, Scope]

def make_unix(path: str) -> Effect[SocketServerService, SocketServerError, Scope]:
    """A server listening on the Unix socket at ``path``."""
    return _listen(lambda factory: get_loop().create_unix_server(factory, path))

make_tls

make_tls(*, cert, key, port=0, host=None, passphrase=None) -> Effect[SocketServerService, SocketServerError, Scope]

A TLS server listening on host:port; a connection reaches the handler once its handshake is done.

ParameterTypeDescription
certPemInput
keyRedacted[PemInput] | PemInput
portint = 0
hoststr | None = None
passphraseRedacted[str] | None = None

Returns Effect[SocketServerService, SocketServerError, Scope]

def make_tls(
    *,
    cert: PemInput,
    key: Redacted[PemInput] | PemInput,
    port: int = 0,
    host: str | None = None,
    passphrase: Redacted[str] | None = None,
) -> Effect[SocketServerService, SocketServerError, Scope]:
    """A TLS server listening on ``host:port``; a connection reaches the
    handler once its handshake is done."""
    redacted_key = key if isinstance(key, Redacted) else Redacted(key)
    options = TlsUpgradeOptions(cert=cert, key=redacted_key, passphrase=passphrase)

    def body() -> Effect[SocketServerService, SocketServerError, Scope]:
        try:
            context = server_context(options)
        except (OSError, ValueError) as cause:
            return fail(SocketServerError(SocketServerOpenError(cause)))
        return _listen(lambda factory: get_loop().create_server(factory, host, port), context)

    return suspend(body)

make_web_socket

make_web_socket(port=0, host=None, **serve_options) -> Effect[SocketServerService, SocketServerError, Scope]

A WebSocket server listening on host:port (port 0: any free port), closed with the scope, on the websockets library (the websockets extra). A handler gets each connection as a Socket, the native socket as WebSocket and the upgrade request as IncomingMessage. serve_options go to websockets' serve (process_request, subprotocols, max_size, 100 MiB by default, ...). A handshake whose Origin AllowedOrigins does not allow (same-origin by default; a client without Origin, such as the DevTools client, is allowed) is refused with 403 before process_request runs.

ParameterTypeDescription
portint = 0
hoststr | None = None
serve_optionsAny = {}

Returns Effect[SocketServerService, SocketServerError, Scope]

def make_web_socket(
    port: int = 0, host: str | None = None, **serve_options: Any
) -> Effect[SocketServerService, SocketServerError, Scope]:
    """A WebSocket server listening on ``host:port`` (port 0: any free
    port), closed with the scope, on the ``websockets`` library (the
    ``websockets`` extra). A handler gets each connection as a ``Socket``,
    the native socket as ``WebSocket`` and the upgrade request as
    ``IncomingMessage``. ``serve_options`` go to ``websockets``' ``serve``
    (``process_request``, ``subprotocols``, ``max_size``, 100 MiB by
    default, ...). A handshake whose ``Origin`` ``AllowedOrigins`` does not
    allow (same-origin by default; a client without ``Origin``, such as
    the DevTools client, is allowed) is refused with 403 before
    ``process_request`` runs."""
    from pyfect.socket._ws_server import make_web_socket as make_on_websockets

    return make_on_websockets(port, host, **serve_options)

layer

layer(port=0, host=None) -> Layer[SocketServer, SocketServerError]
ParameterTypeDescription
portint = 0
hoststr | None = None

Returns Layer[SocketServer, SocketServerError]

def layer(port: int = 0, host: str | None = None) -> Layer[SocketServer, SocketServerError]:
    return layer_effect(SocketServer, make(port, host))

layer_tls

layer_tls(*, cert, key, port=0, host=None) -> Layer[SocketServer, SocketServerError]
ParameterTypeDescription
certPemInput
keyRedacted[PemInput] | PemInput
portint = 0
hoststr | None = None

Returns Layer[SocketServer, SocketServerError]

def layer_tls(
    *, cert: PemInput, key: Redacted[PemInput] | PemInput, port: int = 0, host: str | None = None
) -> Layer[SocketServer, SocketServerError]:
    return layer_effect(SocketServer, make_tls(cert=cert, key=key, port=port, host=host))

layer_web_socket

layer_web_socket(port=0, host=None, **serve_options) -> Layer[SocketServer, SocketServerError]

SocketServer as a make_web_socket WebSocket server.

ParameterTypeDescription
portint = 0
hoststr | None = None
serve_optionsAny = {}

Returns Layer[SocketServer, SocketServerError]

def layer_web_socket(
    port: int = 0, host: str | None = None, **serve_options: Any
) -> Layer[SocketServer, SocketServerError]:
    """``SocketServer`` as a ``make_web_socket`` WebSocket server."""
    return layer_effect(SocketServer, make_web_socket(port, host, **serve_options))