Before you start

Make sure that you can compile and run core tests as described at Configure and Build.

Step by step guide

Typical WebSocket server application in userver consists of the following parts:

WebSocket handler component - main logic of your application
Static config - startup config that does not change for the whole lifetime of an application
Dynamic config - config that could be changed at runtime
int main() - startup code

Let's write a simple chat server that echoes incoming messages as outgoing messages for any websocket connected to /chat URL.

WebSocket handler component

WebSocket handlers must derive from server::websocket::WebsocketHandlerBase and have a name, that is obtainable at compile time via kName variable and is obtainable at runtime via HandlerName().

#include <userver/components/minimal_server_component_list.hpp>
#include <userver/server/websocket/websocket_handler.hpp>
#include <userver/utils/daemon_run.hpp>
 
namespace samples::websocket {
 
class WebsocketsHandler final : public server::websocket::WebsocketHandlerBase {
 public:
  // `kName` is used as the component name in static config
  static constexpr std::string_view kName = "websocket-handler";
 
  // Component is valid after construction and is able to accept requests
  using WebsocketHandlerBase::WebsocketHandlerBase;
 
  void Handle(server::websocket::WebSocketConnection& chat,
              server::request::RequestContext&) const override {
    server::websocket::Message message;
    while (!engine::current_task::ShouldCancel()) {
      chat.Recv(message);
      if (message.close_status) break;
      chat.Send(std::move(message));
    }
    if (message.close_status) chat.Close(*message.close_status);
  }
};
 
}  // namespace samples::websocket

Static config

Now we have to configure the service by providing coro_pool, task_processors and default_task_processor options for the components::ManagerControllerComponent and configuring each component in components section:

# yaml
components_manager:
    coro_pool:
        initial_size: 500             # Preallocate 500 coroutines at startup.
        max_size: 1000                # Do not keep more than 1000 preallocated coroutines.
 
    task_processors:                  # Task processor is an executor for coroutine tasks
 
        main-task-processor:          # Make a task processor for CPU-bound couroutine tasks.
            worker_threads: 4         # Process tasks in 4 threads.
            thread_name: main-worker  # OS will show the threads of this task processor with 'main-worker' prefix.
 
        fs-task-processor:            # Make a separate task processor for filesystem bound tasks.
            thread_name: fs-worker
            worker_threads: 4
 
    default_task_processor: main-task-processor
 
    components:                       # Configuring components that were registered via component_list
        server:
            listener:                 # configuring the main listening socket...
                port: 8080            # ...to listen on this port and...
                task_processor: main-task-processor    # ...process incoming requests on this task processor.
        logging:
            fs-task-processor: fs-task-processor
            loggers:
                default:
                    file_path: '@stderr'
                    level: debug
                    overflow_behavior: discard  # Drop logs if the system is too busy to write them down.
 
        tracer:                       # Component that helps to trace execution times and requests in logs.
            service-name: websocket-server   # "You know. You all know exactly who I am. Say my name. " (c)
 
        dynamic-config:               # Dynamic config storage options, do nothing
            fs-cache-path: ''
        dynamic-config-fallbacks:     # Load options from file and push them into the dynamic config storage.
            fallback-path: dynamic_config_fallback.json
 
        websocket-handler:            # Finally! Websocket handler.
            path: /chat               # Registering handlers '/*' find files.
            method: GET               # Handle only GET requests.
            task_processor: main-task-processor  # Run it on CPU bound task processor
            max-remote-payload: 100000
            fragment-size: 100000

Note that all the components and handlers have their static options additionally described in docs.

Dynamic config

We are not planning to get new dynamic config values in this sample. Because of that we just write the defaults to the fallback file of the components::DynamicConfigFallbacks component.

All the values are described in a separate section Dynamic configs .

{
  "BAGGAGE_SETTINGS": {
    "allowed_keys": []
  },
  "HTTP_CLIENT_CONNECTION_POOL_SIZE": 1000,
  "HTTP_CLIENT_CONNECT_THROTTLE": {
    "max-size": 100,
    "token-update-interval-ms": 0
  },
  "USERVER_BAGGAGE_ENABLED": false,
  "USERVER_CACHES": {},
  "USERVER_CANCEL_HANDLE_REQUEST_BY_DEADLINE": false,
  "USERVER_CHECK_AUTH_IN_HANDLERS": true,
  "USERVER_DEADLINE_PROPAGATION_ENABLED": true,
  "USERVER_DUMPS": {},
  "USERVER_FILES_CONTENT_TYPE_MAP": {
    ".css": "text/css",
    ".gif": "image/gif",
    ".htm": "text/html",
    ".html": "text/html",
    ".jpeg": "image/jpeg",
    ".js": "application/javascript",
    ".json": "application/json",
    ".md": "text/markdown",
    ".png": "image/png",
    ".svg": "image/svg+xml",
    "__default__": "text/plain"
  },
  "USERVER_HANDLER_STREAM_API_ENABLED": false,
  "USERVER_HTTP_PROXY": "",
  "USERVER_LOG_DYNAMIC_DEBUG": {
    "force-disabled": [],
    "force-enabled": []
  },
  "USERVER_LOG_REQUEST": true,
  "USERVER_LOG_REQUEST_HEADERS": false,
  "USERVER_LRU_CACHES": {},
  "USERVER_NO_LOG_SPANS": {
    "names": [],
    "prefixes": []
  },
  "USERVER_RPS_CCONTROL": {
    "down-level": 1,
    "down-rate-percent": 2,
    "min-limit": 10,
    "no-limit-seconds": 1000,
    "overload-off-seconds": 3,
    "overload-on-seconds": 3,
    "up-level": 2,
    "up-rate-percent": 2
  },
  "USERVER_RPS_CCONTROL_ACTIVATED_FACTOR_METRIC": 5,
  "USERVER_RPS_CCONTROL_CUSTOM_STATUS": {},
  "USERVER_RPS_CCONTROL_ENABLED": false,
  "USERVER_TASK_PROCESSOR_PROFILER_DEBUG": {
    "fs-task-processor": {
      "enabled": false,
      "execution-slice-threshold-us": 1000000
    },
    "main-task-processor": {
      "enabled": false,
      "execution-slice-threshold-us": 2000
    }
  },
  "USERVER_TASK_PROCESSOR_QOS": {
    "default-service": {
      "default-task-processor": {
        "wait_queue_overload": {
          "action": "ignore",
          "length_limit": 5000,
          "time_limit_us": 3000
        }
      }
    }
  }
}

A production ready service would dynamically retrieve the above options at runtime from a configuration service. See Writing your own configs server for insights on how to change the above options on the fly, without restarting the service.

int main()

Finally, after writing down the dynamic config values into file at dynamic-config-fallbacks.fallback-path, we add our component to the components::MinimalServerComponentList(), and start the server with static configuration file passed from command line.

int main(int argc, char* argv[]) {
  const auto component_list =
      components::MinimalServerComponentList()
          .Append<samples::websocket::WebsocketsHandler>();
  return utils::DaemonMain(argc, argv, component_list);
}

Build and Run

To build the sample, execute the following build steps at the userver root directory:

mkdir build_release
cd build_release
cmake -DCMAKE_BUILD_TYPE=Release ..
make userver-samples-websocket_service

The sample could be started by running make start-userver-samples-websocket_service. The command would invoke testsuite start target that sets proper paths in the configuration files and starts the service.

To start the service manually run ./samples/websocket_service/userver-samples-websocket_service -c </path/to/static_config.yaml> (do not forget to prepare the configuration files!).

Note: Without file path to static_config.yaml userver-samples-websocket_service will look for a file with name config_dev.yaml; CMake doesn't copy static_config.yaml and dynamic_config_fallback.json files from samples directory into build directory.

Now you can send messages to your server from another terminal:

bash
$ wscat --connect ws://localhost:8080/chat
Connected (press CTRL+C to quit)
> hello
< hello

Functional testing

Functional tests for the service could be implemented using the websocket_client fixture from pytest_userver.plugins.core in the following way:

async def test_echo(websocket_client):
    async with websocket_client.get('chat') as chat:
        await chat.send('hello')
        response = await chat.recv()
        assert response == 'hello'

Do not forget to add the plugin in conftest.py:

pytest_plugins = ['pytest_userver.plugins.core']

Full sources

See the full example at:

⇦ Digest Authorization/Authentication via PostgreSQL | Non-Coroutine Console Tool ⇨