HttpMachine.PCL 6.0.0

HttpMachine

Targets: .NET Standard 2.0 & 2.1, .NET 6, .NET 8 and .NET 10.

Please star this project if you find it useful. Thank you.

Background

This is a fork of the great work done by Benjamin van der Veen. The Original HttpMachine

HttpMachine.PCL is a combined C# HTTP request/response parser. It implements a state machine built with Adrian Thurston's excellent state machine compiler, Ragel.

HttpMachine is Copyright (c) 2011 Benjamin van der Veen. HttpMachine is licensed under the MIT License. See LICENCE.md.

I've forked this project as Benjamin is no longer maintaining the work.

Features

• HTTP/1.1 and 1.0
• Parses requests and responses with one combined parser — filter on MessageType to see which one was parsed
• Supports pipelined messages
• Tells your server if it should keep the connection alive (ShouldKeepAlive)
• Extracts the length of the entity body (Content-Length)
• Supports chunked Transfer-Encoding
• Handles zero-length headers (for example EXT: as used in UPnP)
• Header values are collected in an IEnumerable<string> per header name (repeated headers accumulate)

Usage

using System;
using System.IO;
using System.Linq;
using System.Text;
using HttpMachine;

var data = Encoding.UTF8.GetBytes(
    "HTTP/1.1 200 OK\r\n" +
    "Content-Type: text/plain\r\n" +
    "Content-Length: 14\r\n" +
    "\r\n" +
    "This is a test");

using var handler = new HttpParserDelegate();
using var parser = new HttpCombinedParser(handler);

if (parser.Execute(data) != data.Length)
{
    Console.WriteLine("Parse failed.");
    return;
}

var result = handler.HttpRequestResponse;

Console.WriteLine($"Type: {result.MessageType}");     // Response
Console.WriteLine($"Status: {result.StatusCode}");    // 200
Console.WriteLine($"Keep-alive: {result.ShouldKeepAlive}");

foreach (var header in result.Headers)
{
    Console.WriteLine($"{header.Key}: {string.Join(", ", header.Value)}");
}

result.Body.Position = 0;
Console.WriteLine($"Body: {new StreamReader(result.Body).ReadToEnd()}");

See the console test project for a complete example including chunked transfer encoding, and the test suite for more usage patterns.

Things worth knowing

• Return value of Execute: the number of bytes consumed. If it is less than the length you passed in, the parser hit a parse error at that position.
• Feeding data incrementally: call Execute repeatedly as data arrives; messages may be split across buffers at any point.
• Span support: Execute(ReadOnlySpan<byte>) parses without requiring an array — useful with pooled buffers or PipeReader slices. Body callbacks mirror the input: array-based Execute overloads deliver OnBody(ArraySegment<byte>) over your buffer (as in 5.x); the span overload delivers OnBody(ReadOnlySpan<byte>) to delegates implementing IHttpParserSpanDelegate (which HttpParserDelegate does), or a pooled copy to plain IHttpParserDelegate implementors. Either way the buffer is only valid during the callback — copy it if you keep it.
• End of stream: when a message has no Content-Length and is not chunked, the body runs until the connection closes. Signal this to the parser by calling Execute with an empty buffer.
• Header keys: stored uppercased; the Headers dictionary uses a case-insensitive comparer, so headers["content-type"] works too.
• Delegate results: handler.HttpRequestResponse is the snapshot of the most recently completed message. It is null until the first message has been fully parsed. When parsing pipelined messages, read it from OnMessageEnd (override it) if you need every message.
• Customizing: subclass HttpParserDelegate and override the On... methods you care about, or implement IHttpParserCombinedDelegate from scratch.
• The HTTP method accepts these additional four characters: $ - , .
• When both Content-Length and Transfer-Encoding: chunked are present, chunked wins (RFC 9112 6.3).

Working on the parser (Ragel)

src/main/HttpMachine.netstandard/HttpCombinedParser.cs is generated code — do not edit it by hand. The sources are:

• HttpParser2-chunked.cs.rl — C# host file with the parser actions
• http-chunked.rl — the HTTP grammar
• uri.rl — the URI grammar

To regenerate, install Ragel 6.x (apt install ragel on Debian/Ubuntu, available via Homebrew and Cygwin elsewhere) and run generate.sh from the rl directory. The script also widens a few generated sbyte[] tables to byte[] — Ragel 6.x picks the element type by table length, not value range, and some tables contain values above 127.

Run the tests after regenerating:

cd src/tests/HttpMachine.Tests
dotnet test

Version history

6.0

• Breaking: removed the unused ParserStatus enum.
• Added Execute(ReadOnlySpan<byte>) and the optional IHttpParserSpanDelegate interface for zero-copy body delivery; IHttpParserDelegate is unchanged, so existing delegates keep working.
• Targets .NET 10 instead of .NET 9 (C# 14); .NET Standard 2.0/2.1, .NET 6 and .NET 8 unchanged (System.Memory dependency added for .NET Standard 2.0).
• Performance: Execute(MemoryStream) no longer copies the stream when its buffer is exposable; chunk sizes and status codes are parsed without intermediate string allocations.
• Fixed ShouldKeepAlive for HTTP/1.0 messages (Connection: keep-alive/close were inverted).
• Fixed bodies delimited by connection close (no Content-Length, not chunked); signal EOF with an empty Execute call.
• Fixed repeated headers separated by other headers (previously failed the whole parse).
• The same HttpParserDelegate now works for pipelined/keep-alive message sequences.
• Transfer-Encoding: chunked now takes precedence over Content-Length per RFC 9112.
• Header dictionary lookups are now case-insensitive.
• Added an xunit test suite and CI; repository cleanup (removed bundled ragel.exe and stale build scripts).

4.0+

• .NET Standard 2.0 is now the required minimum version.
• Refactoring and simplification of use has caused some namespaces to change.
• It is no longer necessary to implement the interface IHttpCombinedParser; instead simply new up HttpParserDelegate. Methods can be overridden if needed.
• Header values are collected in an IEnumerable<string>.

3.1.0

• The parser handler must implement IHttpCombinedParser instead of using HttpCombinedParser.

1.1.1

• The parser was combined into one request/response parser. Filter on MessageType to see what type was passed.