xref: /third_party/libwebsockets/lib/roles/README.md (revision d4afb5ce)

## Information for new role implementers

### Introduction

In lws the "role" is the job the wsi is doing in the system, eg,
being an http1 or h2, or ws connection, or being a listen socket, etc.

This is different than, eg, a new ws protocol or a different callback
for an existing role.  A new role is needed when you want to add support for
something completely new, like a completely new wire protocol that
doesn't use http or ws.

So... what's the point of implementing the protocol inside the lws role framework?

You inherit all the well-maintained lws core functionality around:

 - connection lifecycle sequencing in a valgrind-clean way

 - client connection proxy support, for HTTP and Socks5

 - tls support working equally on mbedTLS and OpenSSL and derivatives without any code in the role

 - apis for cert lifecycle management and parsing

 - event loop support working on all the lws event loops (poll, libuv , ev, and event)

 - clean connection tracking and closing even on advanced event loops

 - user code follows the same simple callbacks on wsi

 - multi-vhost support

 - core multithreaded service support with usually no locking requirement on the role code

 - direct compatibility with all other lws roles + protocols in the same event loop

 - compatibility with higher-level stuff like lwsws as the server application

### Code placement

The code specific to that role should live in `./lib/roles/**role name**`

If a role is asymmetic between a client and server side, like http is, it
should generally be implemented as a single role.

### Allowing control over enabling roles

All roles should add a cmake define `LWS_ROLE_**role name**` and make its build
dependent on it in CMakeLists.txt.  Export the cmakedefine in `./cmake/lws_config.h.in`
as well so user builds can understand if the role is available in the lws build it is
trying to bind to.

If the role is disabled in cmake, nothing in its directory is built.

### Role ops struct

The role is defined by `struct lws_role_ops` in `lib/roles/private-lib-roles.h`,
each role instantiates one of these and fills in the appropriate ops
callbacks to perform its job.  By convention that lives in
`./lib/roles/**role name**/ops-**role_name**.c`.

### Private role declarations

Truly private declarations for the role can go in the role directory as you like.
However when the declarations must be accessible to other things in lws build, eg,
the role adds members to `struct lws` when enabled, they should be in the role
directory in a file `private-lib-roles-myrole.h`.

Search for "bring in role private declarations" in `./lib/roles/private-lib-roles.h
and add your private role file there following the style used for the other roles,
eg,

```
#if defined(LWS_ROLE_WS)
 #include "roles/ws/private-lib-roles-ws.h"
#else
 #define lwsi_role_ws(wsi) (0)
#endif
```

If the role is disabled at cmake, nothing from its private.h should be used anywhere.

### Integrating role assets to lws

If your role needs special storage in lws objects, that's no problem.  But to keep
things sane, there are some rules.

 - declare a "container struct" in your private.h for everything, eg, the ws role wants
   to add storage in lws_vhost for enabled extensions, it declares in its private.h

```
struct lws_vhost_role_ws {
#if !defined(LWS_WITHOUT_EXTENSIONS)
	const struct lws_extension *extensions;
#endif
};
```

 - add your role content in one place in the lws struct, protected by `#if defined(LWS_ROLE_**role name**)`,
   eg, again for LWS_ROLE_WS

```
	struct lws_vhost {

...

#if defined(LWS_ROLE_WS)
	struct lws_vhost_role_ws ws;
#endif

...
```

### Adding to lws available roles list

Edit the NULL-terminated array `available_roles` at the top of `./lib/core/context.c` to include
a pointer to your new role's ops struct, following the style already there.

```
const struct lws_role_ops * available_roles[] = {
#if defined(LWS_ROLE_H2)
	&role_ops_h2,
#endif
...
```

This makes lws aware that your role exists, and it can auto-generate some things like
ALPN lists, and call your role ops callbacks for things like hooking vhost creation.

### Enabling role adoption

The primary way wsi get bound to a specific role is via the lws adoption api
`lws_adopt_descriptor_vhost()`.  Add flags as necessary in `./include/libwebsockets/lws-adopt.h`
`enum lws_adoption_type` and follow the existing code in `lws_adopt_descriptor_vhost()`
to bind a wsi with suitable flags to your role ops.

### Implementation of the role

After that plumbing-in is completed, the role ops you declare are "live" on a wsi
bound to them via the adoption api.

The core support for wsis in lws has some generic concepts

 - the wsi holds a pointer member `role_ops` that indicates which role ops the
   wsi is bound to

 - the wsi holds a generic uint32 `wsistate` that contains role flags and wsi state

 - role flags are provided (LWSIFR_CLIENT, LWSIFR_SERVER) to differentiate between
   client and server connections inside a wsi, along with helpers `lwsi_role_client(wsi)`
   and `lwsi_role_server(wsi)`.

 - lws provides around 30 generic states for the wsi starting from 'unconnected' through
   various proxy or tunnel states, to 'established', and then various states shutting
   down until 'dead socket'.  The states have testable flags and helpers to discover if
   the wsi state is before establishment `lwsi_state_est(wsi)` and if in the state it is
   in, it can handle pollout `lwsi_state_can_handle_POLLOUT(wsi)`.

 - You set the initial binding, role flags and state using `lws_role_transition()`.  Afterwards
   you can adjust the state using `lwsi_set_state()`.

### Role ops compression

Since the role ops struct is typically only sparsely filled, rather than have 20 function
pointers most of which may be NULL, there is a separate array of a union of function
pointers that is just long enough for functions that exist in the role, and a nybble index
table with a nybble for each possible op, either 0 indicating that the operation is not
provided in this role, or 1 - 15 indicating the position of the function pointer in the
array.