Simple, scalable, fast, async web server for processing RESTful HTTP/HTTPS requests, written in C#.
Package | NuGet Version | Downloads |
---|---|---|
Watson | ||
Watson.Lite | ||
Watson.Core |
Special thanks to @DamienDennehy for allowing us the use of the Watson.Core
package name in NuGet!
This project is part of the .NET Foundation along with other projects like the .NET Runtime.
- Major refactor with breaking changes to consolidate WatsonWebserver and HttpServerLite
- Consolidated core classes, enums, into WatsonWebserver.Core
- Modified all test apps to support either webserver implementation
- Consolidated and unified constructors across both projects
- Reduced to a single listener prefix
- Removed attribute routes (crossing assembly boundaries and precluding use of AOT)
- Modified Test projects to use base class (to enable testing with Lite version)
- Modified Test projects to allow argument to be passed to indicate if the lite version should be used
- Modified SSL configuration to use only X509Certificate2; derive if filename is supplied
- HttpResponse.StatusDescription now based on StatusCode
- Created a new routing architecture including routing groups, pre-auth routes, and post-auth routes
- Amended HostBuilder extension to allow for balance of route types
- Amended HostBuilder extension to allow for both pre-authentication and post-authentication routes
- Added Test.Routing project and validated with both implementations
- Added Test.HostBuilder project and validated with both implementations
- Added CancellationToken and CancellationTokenSource to HttpContextBase
I'd like to extend a special thanks to those that have helped make Watson Webserver better.
- @notesjor @shdwp @Tutch @GeoffMcGrath @jurkovic-nikola @joreg @Job79 @at1993 @MartyIX
- @pocsuka @orinem @deathbull @binozo @panboy75 @iain-cyborn @gamerhost31 @nhaberl
- @grgouala @sapurtcomputer30 @winkmichael @sqlnew @SaintedPsycho @Return25 @marcussacana
- @samisil @Jump-Suit @ChZhongPengCheng33 @bobaoapae @rodgers-r
Watson is a webserver that operates on top of the underlying http.sys within the operating system. Watson.Lite was created by merging HttpServerLite. Watson.Lite does not have a dependency on http.sys, and is implemented using a TCP implementation provided by CavemanTcp.
The dependency on http.sys (or lack thereof) creates subtle differences between the two libraries, however, the configuration and management of each should be consistent.
Watson.Lite is generally less performant than Watson, because the HTTP implementation is in user space.
- Elevation (administrative privileges) may be required if binding an IP other than 127.0.0.1 or localhost
- For Watson:
- The HTTP HOST header must match the specified binding
- For SSL, the underlying computer certificate store will be used
- For Watson.Lite:
- Watson.Lite uses a TCP listener; your server must be started with an IP address, not a hostname
- The HTTP HOST header does not need to match, since the listener must be defined by IP address
- For SSL, the certificate filename, filename and password, or
X509Certificate2
must be supplied
Watson and Watson.Lite always routes in the following order (configure using Webserver.Routes
):
.Preflight
- handling preflight requests (generally with HTTP methodOPTIONS
).PreRouting
- always invoked before any routing determination is made.PreAuthentication
- a routing group, comprised of:.Static
- static routes, e.g. an HTTP method and an explicit URL.Content
- file serving routes, e.g. a directory where files can be read.Parameter
- routes where variables are specified in the path, e.g./user/{id}
.Dynamic
- routes where the URL is defined by a regular expression
.AuthenticateRequest
- demarcation route between unauthenticated and authenticated routes.PostAuthentication
- a routing group with a structure identical to.PreAuthentication
.Default
- the default route; all requests go here if not routed previously.PostRouting
- always invoked, generally for logging and telemetry
If you do not wish to use authentication, you should map your routes in the .PreAuthentication
routing group (though technically they can be placed in .PostAuthentication
or .Default
assuming the AuthenticateRequest
method is null.
As a general rule, never try to send data to an HttpResponse
while in the .PostRouting
route. If a response has already been sent, the attempt inside of .PostRouting
will fail.
It is recommended that you implement authentication in .AuthenticateRequest
. Should a request fail authentication, return a response within that route. The HttpContextBase
class has properties that can hold authentication-related or session-related metadata, specifically, .Metadata
.
By default, Watson and Watson.Lite will permit all inbound connections.
- If you want to block certain IPs or networks, use
Server.AccessControl.DenyList.Add(ip, netmask)
- If you only want to allow certain IPs or networks, and block all others, use:
Server.AccessControl.Mode = AccessControlMode.DefaultDeny
Server.AccessControl.PermitList.Add(ip, netmask)
using System.IO;
using System.Text;
using WatsonWebserver;
static void Main(string[] args)
{
Server server = new Server("127.0.0.1", 9000, false, DefaultRoute);
server.Start();
Console.ReadLine();
}
static async Task DefaultRoute(HttpContextBase ctx) =>
await ctx.Response.Send("Hello from the default route!");
Then, open your browser to http://127.0.0.1:9000/
.
Refer to Test.Routing
for a full example.
using System.IO;
using System.Text;
using System.Text.RegularExpressions;
using WatsonWebserver;
static void Main(string[] args)
{
Server server = new Server("127.0.0.1", 9000, false, DefaultRoute);
// add content routes
server.Routes.PreAuthentication.Content.Add("/html/", true);
server.Routes.PreAuthentication.Content.Add("/img/watson.jpg", false);
server.Routes.PreAuthentication.ContentHandler = new ContentRouteHandler(server.Routes.PreAuthentication.Content);
// add static routes
server.Routes.PreAuthentication.Static.Add(HttpMethod.GET, "/hello/", GetHelloRoute);
server.Routes.PreAuthentication.Static.Add(HttpMethod.GET, "/howdy/", async (HttpContextBase ctx) =>
{
await ctx.Response.Send("Hello from the GET /howdy static route!");
return;
});
// add parameter routes
server.Routes.PreAuthentication.Parameter.Add(HttpMethod.GET, "/{version}/bar", GetBarRoute);
// add dynamic routes
server.Routes.PreAuthentication.Dynamic.Add(HttpMethod.GET, new Regex("^/foo/\\d+$"), GetFooWithId);
server.Routes.PreAuthentication.Dynamic.Add(HttpMethod.GET, new Regex("^/foo/?$"), GetFoo);
// start the server
server.Start();
Console.WriteLine("Press ENTER to exit");
Console.ReadLine();
}
static async Task GetHelloRoute(HttpContextBase ctx) =>
await ctx.Response.Send("Hello from the GET /hello static route!");
static async Task GetBarRoute(HttpContextBase ctx) =>
await ctx.Response.Send("Hello from the GET /" + ctx.Request.Url.Parameters["version"] + "/bar route!");
static async Task GetFooWithId(HttpContextBase ctx) =>
await ctx.Response.Send("Hello from the GET /foo/[id] dynamic route!");
static async Task GetFoo(HttpContextBase ctx) =>
await ctx.Response.Send("Hello from the GET /foo/ dynamic route!");
static async Task DefaultRoute(HttpContextBase ctx) =>
await ctx.Response.Send("Hello from the default route!");
Server server = new Server("127.0.0.1", 9000, false, DefaultRoute);
// set default permit (permit any) with deny list to block specific IP addresses or networks
server.Settings.AccessControl.Mode = AccessControlMode.DefaultPermit;
server.Settings.AccessControl.DenyList.Add("127.0.0.1", "255.255.255.255");
// set default deny (deny all) with permit list to permit specific IP addresses or networks
server.Settings.AccessControl.Mode = AccessControlMode.DefaultDeny;
server.Settings.AccessControl.PermitList.Add("127.0.0.1", "255.255.255.255");
Watson supports both receiving chunked data and sending chunked data (indicated by the header Transfer-Encoding: chunked
).
Refer to Test.ChunkServer
for a sample implementation.
static async Task UploadData(HttpContextBase ctx)
{
if (ctx.Request.ChunkedTransfer)
{
bool finalChunk = false;
while (!finalChunk)
{
Chunk chunk = await ctx.Request.ReadChunk();
// work with chunk.Length and chunk.Data (byte[])
finalChunk = chunk.IsFinalChunk;
}
}
else
{
// read from ctx.Request.Data stream
}
}
static async Task DownloadChunkedFile(HttpContextBase ctx)
{
using (FileStream fs = new FileStream("./img/watson.jpg", , FileMode.Open, FileAccess.Read))
{
ctx.Response.StatusCode = 200;
ctx.Response.ChunkedTransfer = true;
byte[] buffer = new byte[4096];
while (true)
{
int bytesRead = await fs.ReadAsync(buffer, 0, buffer.Length);
if (bytesRead > 0)
{
await ctx.Response.SendChunk(buffer, bytesRead);
}
else
{
await ctx.Response.SendFinalChunk(null, 0);
break;
}
}
}
return;
}
HostBuilder
helps you set up your server much more easily by introducing a chain of settings and routes instead of using the server class directly. Special thanks to @sapurtcomputer30 for producing this fine feature!
Refer to Test.HostBuilder
for a full sample implementation.
using WatsonWebserver.Extensions.HostBuilderExtension;
Server server = new HostBuilder("127.0.0.1", 8000, false, DefaultRoute)
.MapStaticRoute(HttpMethod.GET, GetUrlsRoute, "/links")
.MapStaticRoute(HttpMethod.POST, CheckLoginRoute, "/login")
.MapStaticRoute(HttpMethod.POST, TestRoute, "/test")
.Build();
server.Start();
Console.WriteLine("Server started");
Console.ReadKey();
static async Task DefaultRoute(HttpContextBase ctx) =>
await ctx.Response.Send("Hello from default route!");
static async Task GetUrlsRoute(HttpContextBase ctx) =>
await ctx.Response.Send("Here are your links!");
static async Task CheckLoginRoute(HttpContextBase ctx) =>
await ctx.Response.Send("Checking your login!");
static async Task TestRoute(HttpContextBase ctx) =>
await ctx.Response.Send("Hello from the test route!");
When you configure Watson to listen on 127.0.0.1
or localhost
, it will only respond to requests received from within the local machine.
To configure access from other nodes outside of localhost
, use the following:
- Specify the exact DNS hostname upon which Watson should listen in the Server constructor
- The HOST header on HTTP requests MUST match the supplied listener value (operating system limitation)
- If you want to listen on more than one hostname or IP address, use
*
or+
. You MUST run as administrator (operating system limitation) - If you want to use a port number less than 1024, you MUST run as administrator (operating system limitation)
- Open a port on your firewall to permit traffic on the TCP port upon which Watson is listening
- You may have to add URL ACLs, i.e. URL bindings, within the operating system using the
netsh
command:- Check for existing bindings using
netsh http show urlacl
- Add a binding using
netsh http add urlacl url=http://[hostname]:[port]/ user=everyone listen=yes
- Where
hostname
andport
are the values you are using in the constructor - If you are using SSL, you will need to install the certificate in the certificate store and retrieve the thumbprint
- Refer to https://github.com/jchristn/WatsonWebserver/wiki/Using-SSL-on-Windows for more information, or if you are using SSL
- Check for existing bindings using
- If you're still having problems, start a discussion here, and I will do my best to help and update the documentation.
When you configure Watson.Lite to listen on 127.0.0.1
, it will only respond to requests received from within the local machine.
To configure access from other nodes outside of the local machine, use the following:
- Specify the IP address of the network interface on which Watson.Lite should listen
- If you want to listen on more than one network interface, use
*
or+
. You MUST run as administrator (operating system limitation) - If you want to use a port number less than 1024, you MUST run as administrator (operating system limitation)
- Open a port on your firewall to permit traffic on the TCP port upon which Watson is listening
- If you are using SSL, you will need to have one of the following when instantiating:
- The
X509Certificate2
object - The filename and password to the certificate
- The
- If you're still having problems, start a discussion here, and I will do my best to help and update the documentation.
Please refer to the Test.Docker
project and the Docker.md
file therein.
Refer to CHANGELOG.md for version history.