FnKit.Functions.Framework 0.1.0

fnkit — MQTT Functions Framework for .NET

An open source FaaS (Function as a Service) framework for writing portable .NET functions invoked via MQTT messages instead of HTTP requests.

Adapted from the Google Cloud Functions Framework for .NET.

How It Works

Instead of standing up an HTTP server, fnkit connects to an MQTT broker and subscribes to a topic based on your function name. When a message arrives, your function is invoked with (request, response) arguments.

MQTT Message → Broker → fnkit subscribes → Your Function(req, res) → Optional MQTT Response

Prerequisites

The fnkit Functions Framework for .NET requires .NET 8.0 or later.

Quick Start

1. Create a .NET project

mkdir MyFunction && cd MyFunction
dotnet new console
dotnet add package FnKit.Functions.Framework
dotnet add package FnKit.Functions.Hosting

2. Create your function

// HelloFunction.cs
using FnKit.Functions.Framework;

public class HelloFunction : IMqttFunction
{
    public Task HandleAsync(MqttRequest request, MqttResponse response, CancellationToken cancellationToken)
    {
        string name = "World";
        if (request.Body.HasValue &&
            request.Body.Value.TryGetProperty("name", out var nameProp))
        {
            name = nameProp.GetString() ?? "World";
        }

        response.Send(new { message = $"Hello, {name}!" });
        return Task.CompletedTask;
    }
}

3. Create the entry point

// Program.cs
using FnKit.Functions.Hosting;

return await EntryPoint.StartAsync(typeof(HelloFunction).Assembly, args);

4. Run it

FUNCTION_TARGET=HelloFunction dotnet run
# Output: [fnkit] Listening on topic: fnkit/HelloFunction

5. Test it

# In another terminal, publish a message
mosquitto_pub -h localhost -t fnkit/HelloFunction -m '{"name": "Max"}'

Function Signature

fnkit uses an interface-based pattern consistent with the .NET Functions Framework:

public class MyFunction : IMqttFunction
{
    public Task HandleAsync(MqttRequest request, MqttResponse response, CancellationToken cancellationToken)
    {
        // request — MQTT request object
        // response — MQTT response object
        // cancellationToken — cancellation token
        return Task.CompletedTask;
    }
}

Request Object (MqttRequest)

Use request.GetBody<T>() for typed deserialization of the JSON body.

Response Object (MqttResponse)

Fire-and-Forget

Functions don't have to send a response. Just process the message and return:

public class LoggerFunction : IMqttFunction
{
    public Task HandleAsync(MqttRequest request, MqttResponse response, CancellationToken cancellationToken)
    {
        Console.WriteLine($"Event received: {request.BodyText}");
        // No response.Send() needed — fire and forget
        return Task.CompletedTask;
    }
}

Response Topics

Responses are published to (in order of precedence):

1. MQTT v5 Response Topic — If the incoming message has a ResponseTopic property
2. Default — fnkit/{functionName}/response

Correlation data from the incoming message is automatically forwarded.

Configuration

Configure via CLI flags or environment variables. CLI flags take precedence.

If FUNCTION_TARGET is not specified and the assembly contains exactly one IMqttFunction implementation, it is used automatically (same pattern as the Google Cloud Functions Framework).

Security

TLS (Port 8883)

FUNCTION_TARGET=HelloFunction dotnet run -- --broker=mqtts://broker:8883 --ca=/path/to/ca.crt

mTLS (Mutual TLS)

FUNCTION_TARGET=HelloFunction dotnet run -- \
  --broker=mqtts://broker:8883 \
  --ca=/path/to/ca.crt \
  --cert=/path/to/client.crt \
  --key=/path/to/client.key

Username/Password

FUNCTION_TARGET=HelloFunction dotnet run -- --broker=mqtt://broker:1883 --username=user --password=pass

MQTT v5 Features

fnkit uses MQTT v5 by default, enabling:

• Response Topics — Request-reply pattern via ResponseTopic property
• Correlation Data — Match responses to requests
• User Properties — Key-value metadata on messages (like HTTP headers)
• Content Type — Indicate payload format

Comparison with HTTP Functions Framework

Architecture

See the design docs for:

• Architecture — System overview and components
• Contract — The MQTT Functions Framework contract (language-agnostic)
• Decisions — Design decisions and rationale

Based On

This framework is adapted from the Google Cloud Functions Framework for .NET (Apache-2.0 License). The function resolution, assembly scanning, and framework patterns are reused. The HTTP transport layer has been replaced with MQTT using MQTTnet.

License

Apache-2.0 — See LICENSE for details.