Neuron HTTP router - Neuron Agent API

Overview

Neuro.Networking.HttpRouter supports two complementary styles:

Manual endpoint registration with RegisterGet, RegisterPost, RegisterPut, RegisterPatch, RegisterDelete, and RegisterOptions
Attribute-based controllers with per-request controller instances, binding, validation, staged middleware, and automatic JSON responses

This guide starts with the controller model because it is the package’s intended high-level API, but the same router also exposes lower-level primitives when you need direct control.

The main package documented here is Neuro.Networking.HttpRouter. Controller-based APIs also use types from Neuro.Networking.HttpRouter.Core, and OpenAPI generation uses the companion Neuro.Networking.HttpRouter.OpenApi assembly.

Install the package

dotnet add package Neuro.Networking.HttpRouter

or:

<ItemGroup>
  <PackageReference Include="Neuro.Networking.HttpRouter" />
</ItemGroup>

Minimal setup

Create a ControllerEndpointRouter, register it with your HTTP server, and then either scan an assembly or register one controller directly.

using Neuro.Networking.HttpRouter;
using Neuro.Networking.HttpRouter.Core;
using Waher.Networking.HTTP;

HttpServer Server = new HttpServer(8080);
ControllerEndpointRouter Router = new ControllerEndpointRouter(
    "/api",
    true,
    new CamelCaseParameterNameCodec());

Server.Register(Router);
Router.RegisterControllers(typeof(UsersController).Assembly);

// Or register a single controller explicitly:
// Router.RegisterController<UsersController>();

With that setup, a controller route like /users becomes available under /api/users.

Current feature surface

The current router surface includes:

Per-request controller instances and constructor injection through Router.ServiceProvider
Transport validation on bound parameters and body models
A staged middleware pipeline from Infrastructure through PostHandler
Router-level authentication scheme registration through UseAuthenticationScheme(...)
Configurable JSON field naming through the router’s IParameterNameCodec
OpenAPI document generation from the registered route tree

A first mental model

When a request hits the router:

Matches the HTTP method and path
Runs any middleware registered for that route and stage
Creates a controller instance for the request
Binds route, query, and body values to method parameters and validates them
Calls the controller action
Serializes the returned object to JSON unless the action is raw

First example

[Controller]
[Route("/users")]
public sealed class UsersController : ControllerBase
{
    [HttpGet("/[userId]")]
    public Task<UserResponse> Get(string UserId)
    {
        return Task.FromResult(new UserResponse
        {
            UserId = UserId,
            DisplayName = "Ada"
        });
    }
}

public sealed class UserResponse
{
    public string UserId { get; set; } = string.Empty;
    public string DisplayName { get; set; } = string.Empty;
}

A GET request to /api/users/42 returns JSON based on the UserResponse object.

A good default order

ControllerEndpointRouter Router = new ControllerEndpointRouter(
    "/api",
    true,
    new CamelCaseParameterNameCodec());

Router.RegisterMiddleware("/users/*", (HttpContext Context, Action<HttpContext> Next) =>
{
    Next(Context);
    return Task.CompletedTask;
});

Router.RegisterControllers(typeof(UsersController).Assembly);

Router-level authentication helpers

The router can also advertise authentication schemes for the endpoints it serves.

ControllerEndpointRouter Router = new ControllerEndpointRouter(
    "/api",
    true,
    new CamelCaseParameterNameCodec());

Router.UseAuthenticationScheme(HttpAuthenticationSchemes.GetAccountsAuthenticationScheme());
Router.UseAuthenticationScheme(HttpAuthenticationSchemes.GetLegalSignatureScheme());
Router.UseAuthenticationScheme(HttpAuthenticationSchemes.GetAnonymousScheme());

Call UseAuthenticationScheme(...) with a custom HttpAuthenticationScheme when the built-in account, legal-signature, or anonymous schemes are not enough.

OpenAPI document generation

The Neuro.Networking.HttpRouter.OpenApi companion assembly can generate an OpenAPI document from the routes registered on a ControllerEndpointRouter. The generator returns the typed OpenApiDocument model from Neuro.Content.OpenApi, which also provides the JSON content codec used when the document is returned over HTTP. Parklet exposes this as a normal endpoint:

using Neuro.Content.OpenApi.Model;
using Neuro.Networking.HttpRouter;
using Neuro.Networking.HttpRouter.Core;
using Neuro.Networking.HttpRouter.OpenApi;

public sealed class ParkletHttpService
{
    public ParkletHttpService(ControllerEndpointRouter Router)
    {
        Router.RegisterGet("/open-api", async (ExtendedHttpRequest Req, HttpResponse Res) =>
        {
            OpenApiDocument Document = OpenApiGenerator.Generate(
                Router,
                new OpenApiInfo
                {
                    Title = "Parklet API",
                    Version = "3.0.0"
                });

            Document.Servers.AddRange(OpenApiGenerator.CurrentServers());
            await Res.Return(Document);
        });

        Router.RegisterControllers(typeof(ParkletHttpService).Assembly);
    }
}

The generator reads the router’s route tree and emits an OpenAPI 3.0.3 document. It infers paths, route parameters, query parameters, request bodies, response schemas, and security metadata from registered controllers and manual endpoints. It also uses the active IParameterNameCodec, so a router configured with SnakeCaseParameterNameCodec produces snake-case JSON schema fields. Use [Summary], [Description], and [Tag] from Neuro.Networking.HttpRouter.OpenApi to improve operation text and grouping in generated docs.

​Overview

​Install the package

​Minimal setup

​Current feature surface

​A first mental model

​First example

​A good default order

​Router-level authentication helpers

​OpenAPI document generation

​What to read next

Overview

Install the package

Minimal setup

Current feature surface

A first mental model

First example

A good default order

Router-level authentication helpers

OpenAPI document generation

What to read next