lws-io-ops.h

Go to the documentation of this file.

/*
 * libwebsockets - small server side websockets and web server implementation
 *
 * Copyright (C) 2010 - 2026 Andy Green <andy@warmcat.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 *
 * lws-io-ops.h: the requests the sansIO half of lws makes of the IO half.
 * See READMEs/README.sans-io-split.md, "The interface" and "The headers".
 *
 * sansIO asks IO for exactly these, and nothing else: the four requests
 * of the loop (call my tx when the transport can take bytes, feed or stop
 * feeding my rx, the earliest deadline moved, release my transport), which
 * it spells as it always has (lws_callback_on_writable(),
 * lws_rx_flow_control(), lws_set_timeout() and lws_sul_schedule(),
 * lws_close_free_wsi()) and which reach this struct at the bottom; the
 * connection object's (made, moved to another object, its datagram path);
 * and, grouped below by theme, the client transport, the tls session, tx,
 * service, the app's rx pull and the vhost.  The platform's clock and
 * random source, lws_now_usecs() and lws_get_random(), are dependencies
 * rather than requests.  What sansIO asks of features lws' own IO provides
 * (a cgi child process, a jit-trust vhost) is not here: no other IO
 * supplies them, and they are private to lws.  README.sans-io-split.md,
 * "The contract", lists them.
 *
 * IO fills it in for the normal build (lws_io_ops_default).  An embedder of
 * the sansIO half alone supplies its own in
 * lws_context_creation_info.io_ops, and a port that returns its requests as
 * polled outputs implements the same.
 *
 * The struct is one ABI whatever the build: every member is declared in
 * every build, and one whose feature a build lacks is NULL there.  Its
 * version is LWS_IO_OPS_ABI_VERSION, and a table handed in must carry the
 * version the embedder was compiled with in its abi_version, or context
 * creation fails, saying so.
 */
 
/*
 * The version of lws_io_ops_t: its members, their order and what they
 * mean.  Any change to them changes it.
 */
#define LWS_IO_OPS_ABI_VERSION 5
 
/*
 * The close request reaches the transport in phases, in this order over a
 * connection's close: not every close has every phase
 */
enum lws_io_close_phase {
        LWS_IOCLOSE_QUIESCE,    /* nothing of the transport's may act on the
                                 * wsi any more: connect attempts and their
                                 * timers, dns, the wait for a socket */
        LWS_IOCLOSE_UNWATCH,    /* stop watching the transport, keep it for
                                 * the release (a restart follows, or a
                                 * file's user hears it close first) */
        LWS_IOCLOSE_SHUTDOWN,   /* stop sending: a tls close_notify when there
                                 * is a session, else the write side */
        LWS_IOCLOSE_STAGE,      /* keep the transport until the peer has
                                 * finished, and say when it has */
        LWS_IOCLOSE_RELEASE,    /* release it all: tls session, fd, its place
                                 * in the poll set */
};
 
/*
 * A datagram connection's path: which address its datagrams go to is its
 * protocol's decision (quic's connection migration, RFC 9000 9); the socket
 * that reaches it is IO's
 */
enum lws_io_path_op {
        LWS_IOPATH_COMMIT,      /* the peer is at this address now: report it
                                 * as the connection's peer, and aim a
                                 * connected socket there if it is not */
        LWS_IOPATH_NEW_SOCKET,  /* move onto a fresh socket (a new local
                                 * port) connected to this address, closing
                                 * the old; the reported peer is unchanged */
        LWS_IOPATH_RELAYED,     /* a server connection was just born, and
                                 * committed to its peer, from a datagram IO
                                 * delivered as carried by a relay at this
                                 * address: the peer is the relay's claim, and
                                 * is reached through the relay */
        LWS_IOPATH_PROVEN,      /* the protocol validated the path to the
                                 * peer at this address (quic address
                                 * validation, RFC 9000 8): what carried it,
                                 * eg, a relay, is proven along with it */
};
 
struct lws_client_connect_info;
 
typedef struct lws_io_ops {
        uint32_t abi_version;
 
        int (*want_write)(struct lws *wsi);
        int (*want_read)(struct lws *wsi, int on);
        void (*deadline)(struct lws_context *cx, int tsi, lws_usec_t us);
        int (*close)(struct lws *wsi, int phase);
        int (*path)(struct lws *wsi, int op, const union lws_sockaddr46 *peer);
        void (*created)(struct lws *wsi);
        int (*transfer)(struct lws *from, struct lws *to);
 
        /*
         * the transport: a client's, as its protocol decides about it, and
         * what IO knows of a connection's peer
         */
 
        struct lws *(*transport_start)(struct lws *wsi);
        int (*transport_connected)(struct lws *wsi);
        void (*transport_established)(struct lws *wsi);
        int (*transport_failed)(struct lws *wsi);
        struct lws *(*client_connect)(const struct lws_client_connect_info *i);
        const char *(*peer_address)(struct lws *wsi, char *buf, size_t len);
        const char *(*peer_describe)(struct lws *wsi, char *buf, size_t len,
                                     int flags);
#if defined(LWS_WITH_NETWORK)
        /* the peer stack's types only exist with networking */
        int (*peer_walk)(struct lws *wsi, lws_peer_entry_t *dest, int max);
        int (*peer_raise)(struct lws *wsi, const lws_sockaddr46 *seen,
                          lws_peer_cred_t cred);
#endif
 
        /*
         * the tls session, which is IO's: what sansIO asks of it.  NULL in a
         * build without tls.
         */
 
        void *(*tls_session)(struct lws *wsi);
        const uint8_t *(*tls_hs_ca_id)(struct lws *wsi);
        int (*tls_peer_cert_info)(struct lws *wsi, enum lws_tls_cert_info type,
                                  union lws_tls_cert_info_results *buf,
                                  size_t len);
 
        /*
         * quic runs the tls handshake inside its own packets: these must be
         * set in a build with quic and tls, and are NULL in one without
         */
 
        int (*tls_quic_session)(struct lws *wsi, lws_tls_quic_secret_cb cb);
        int (*tls_quic_handshake)(struct lws *wsi, int level, const uint8_t *in,
                                  size_t in_len, uint8_t *out, size_t *out_len);
        int (*tls_quic_set_tp)(struct lws *wsi, const uint8_t *tp, size_t tp_len);
        int (*tls_quic_get_tp)(struct lws *wsi, const uint8_t **tp,
                               size_t *tp_len);
        int (*tls_confirm_peer_cert)(struct lws *wsi, char *ebuf,
                                     size_t ebuf_len);
        int (*tls_quic_aead)(struct lws *wsi);
        int (*tls_quic_alert)(struct lws *wsi);
        int (*tls_quic_alpn)(struct lws *wsi, char *buf, size_t len);
        int (*tls_quic_admit)(struct lws *wsi);
 
        /*
         * tx: the transport taking sansIO's bytes
         */
 
        int (*tx_push)(struct lws *wsi, unsigned char *buf, size_t len);
        void (*tx_now)(struct lws *wsi);
        int (*tx_choked)(struct lws *wsi);
        int (*tx_file)(struct lws *wsi);
 
        /*
         * service: sansIO's handling of a connection, run now
         */
 
        int (*service_writable)(struct lws *wsi);
        int (*service_now)(struct lws *wsi);
        int (*flag_pending_rx)(struct lws *wsi);
        void (*wake)(struct lws *wsi);
 
        /*
         * rx at the app's pace
         */
 
        int (*http_client_read)(struct lws *wsi, char **buf, int *len);
 
        /*
         * the vhost and the context: a vhost's creation and destruction are
         * IO's, and so is the process the context runs in
         */
 
        int (*finalize_startup)(struct lws_context *cx, const char *where);
 
        void (*vhost_destroy)(struct lws_vhost *vh);
} lws_io_ops_t;
 
/*
 * IO's own: the requests reach the poll set and the socket.  An embedder
 * that only wants to hear the requests starts its table from this one with
 * lws_io_ops_init() and wraps the ops it listens to (api-test-sansio does).
 */
LWS_VISIBLE LWS_EXTERN_FOR_DATA const lws_io_ops_t lws_io_ops_default;

static LWS_INLINE void
lws_io_ops_init(lws_io_ops_t *ops)
{
        *ops = lws_io_ops_default;
        ops->abi_version = LWS_IO_OPS_ABI_VERSION;
}