Websockets

Ocelot supports proxying WebSockets with some extra bits. This functionality was requested in issue 212.

In order to get WebSocket proxying working with Ocelot you need to do the following. In your Configure method you need to tell your application to use WebSockets:

Configure(app =>
{
    app.UseWebSockets();
    app.UseOcelot().Wait();
})

Then in your ocelot.json add the following to proxy a Route using WebSockets:

{
  "UpstreamPathTemplate": "/",
  "DownstreamPathTemplate": "/ws",
  "DownstreamScheme": "ws",
  "DownstreamHostAndPorts": [
    { "Host": "localhost", "Port": 5001 }
  ]
}

With this configuration set Ocelot will match any WebSocket traffic that comes in on / and proxy it to localhost:5001/ws. To make this clearer Ocelot will receive messages from the upstream client, proxy these to the downstream service, receive messages from the downstream service and proxy these to the upstream client.

SignalR

Ocelot supports proxying SignalR. This functionality was requested in issue 344. In order to get WebSocket proxying working with Ocelot you need to do the following.

First, install SignalR Client NuGet package:

NuGet\Install-Package Microsoft.AspNetCore.SignalR.Client

The package is deprecated, but new versions are still built from the source code. So, SignalR is the part of the ASP.NET Framework which can be referenced like:

<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

More information on framework compatibility can be found in instrictions: Use ASP.NET Core APIs in a class library.

Second, you need to tell your application to use SignalR. Complete reference is here: ASP.NET Core SignalR configuration

public void ConfigureServices(IServiceCollection services)
{
    services.AddOcelot();
    services.AddSignalR();
}

Pay attention to configuration of transport level of WebSockets, so configure allowed transports to allow WebSockets connections.

Then in your ocelot.json add the following to proxy a Route using SignalR. Note normal Ocelot routing rules apply the main thing is the scheme which is set to ws.

{
  "UpstreamHttpMethod": [ "GET", "POST", "PUT", "DELETE", "OPTIONS" ],
  "UpstreamPathTemplate": "/gateway/{catchAll}",
  "DownstreamPathTemplate": "/{catchAll}",
  "DownstreamScheme": "ws",
  "DownstreamHostAndPorts": [
    { "Host": "localhost", "Port": 5001 }
  ]
}

WebSocket Secure

If you define a route with Secured WebSocket protocol, use the wss scheme:

{
  "DownstreamScheme": "wss",
  // ...
}

Keep in mind: you can use WebSocket SSL for both SignalR and WebSockets.

To understand wss scheme, browse to this:

If you have questions, it may be helpful to search for documentation on MS Learn:

SSL Errors

If you want to ignore SSL warnings (errors), set the following in your Route config:

{
  "DownstreamScheme": "wss",
  "DangerousAcceptAnyServerCertificateValidator": true,
  // ...
}

But we don’t recommend doing this! Read the official notes regarding SSL Errors in the Configuration doc, where you will also find best practices for your environments.

Note, the wss scheme fake validator was added by PR 1377, as a part of issues 1375, 1237 and etc. This life hacking feature for self-signed SSL certificates is available in version 20.0. It will be removed and/or reworked in future releases. See the SSL Errors section for details.

Supported

  1. Load Balancer

  2. Routing

  3. Service Discovery

This means that you can set up your downstream services running WebSockets and either have multiple DownstreamHostAndPorts in your Route config, or hook your Route into a service discovery provider and then load balance requests… Which we think is pretty cool.

Not Supported

Unfortunately a lot of Ocelot features are non WebSocket specific, such as header and http client stuff. We have listed what will not work below:

  1. Tracing

  2. Request ID

  3. Request Aggregation

  4. Rate Limiting

  5. Quality of Service

  6. Middleware Injection

  7. Headers Transformation

  8. Delegating Handlers

  9. Claims Transformation

  10. Caching

  11. Authentication [1]

  12. Authorization

We are not 100% sure what will happen with this feature when it gets into the wild, so please make sure you test thoroughly!

Future

Websockets and SignalR are being developed intensively by the .NET community, so you need to watch for trends, releases in official docs regularly:

As a team, we cannot advise you on development, but feel free to ask questions, get coding recipes in the Discussions space of the repository. octocat

Also, we welcome any bug reports, enhancements or proposals regarding this feature.

The Ocelot team considers the current impementation of WebSockets feature obsolete, based on the WebSocketsProxyMiddleware class. Websockets are the part of ASP.NET Core framework having native WebSocketMiddleware class. We have a strong intention to migrate or at least redesign the feature, see issue 1707.