Skip to content

Write a native worker

Build, package and deploy a NativeDllEngine worker. The C ABI, the wire format and the caveats are in NativeDllEngine Workers.

1. Vendor the C headers

# From your native worker project
cp /path/to/workmanager/src/Virtufin.Worker.Host/Schemas/virtufin_worker_api_c.h .
cp /path/to/workmanager/src/Virtufin.Worker.Host/Schemas/virtufin_worker_api_pb.h .

virtufin_worker_api_c.h is the ABI: the VirtufinHost struct, the Process/FreeResult signatures and the status codes. virtufin_worker_api_pb.h is a header-only C99 codec for the two protobuf messages; it needs no protobuf runtime. Both headers also compile as C++. A worker in another language can use any protobuf library with the CloudEvents cloudevents.proto instead of the codec header.

2. Implement the Worker

The worker exports two functions. This one replies to every event with one greeting, under an id derived from the input's and keeping the input's correlationid:

#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#include "virtufin_worker_api_c.h"
#include "virtufin_worker_api_pb.h"

int32_t Process(const VirtufinHost* host,
                const uint8_t* in_buf,
                int32_t in_len,
                uint8_t** out_buf,
                int32_t* out_len) {
    vf_cloud_event in;
    vf_writer reply, batch;
    const vf_attr* correlation;
    static const char suffix[] = "/reply";
    uint8_t* reply_id;
    vf_bytes reply_id_bytes;

    *out_buf = NULL;
    *out_len = 0;
    /* 1. Decode the request: views into in_buf, no allocation. */
    if (in_len < 0 || vf_decode_cloud_event(in_buf, (size_t)in_len, &in) != VF_OK) {
        static const char msg[] = "myworker: malformed CloudEvent";
        uint8_t* bytes = malloc(sizeof msg - 1);
        if (bytes == NULL) return VIRTUFIN_STATUS_INTERNAL_FAILURE;
        memcpy(bytes, msg, sizeof msg - 1);
        *out_buf = bytes;
        *out_len = sizeof msg - 1;
        return VIRTUFIN_STATUS_WORKER_ERROR;   /* reported as this event's error */
    }
    host->log(host->engine_ptr, 2, "myworker: received an event");

    /* 2. The output's own id: the input's plus a suffix, never the input's. */
    reply_id_bytes.len = in.id.len + sizeof suffix - 1;
    reply_id = malloc(reply_id_bytes.len);
    if (reply_id == NULL) return VIRTUFIN_STATUS_INTERNAL_FAILURE;
    memcpy(reply_id, in.id.ptr, in.id.len);
    memcpy(reply_id + in.id.len, suffix, sizeof suffix - 1);
    reply_id_bytes.ptr = reply_id;

    /* 3. Build the outputs: one vf_writer per event, appended in publish order. */
    vf_writer_init(&reply);
    vf_writer_init(&batch);
    vf_event_core(&reply, reply_id_bytes, VF_STR("urn:com.example.myworker"), VF_STR("com.example.myworker.reply"));
    free(reply_id);                            /* the writer copied it */
    vf_event_attr_string(&reply, VF_STR("inputid"), in.id);
    vf_event_attr_string(&reply, VF_STR("datacontenttype"), VF_STR("application/json"));
    correlation = vf_find_attr(&in, "correlationid");
    if (correlation != NULL) vf_event_attr(&reply, correlation);
    vf_event_text_data(&reply, VF_STR("{\"greeting\":\"hello\"}"));
    vf_batch_add(&batch, &reply);
    vf_writer_free(&reply);
    if (batch.failed) {
        vf_writer_free(&batch);
        return VIRTUFIN_STATUS_INTERNAL_FAILURE;
    }

    /* 4. Hand the malloc()ed batch to the engine; it calls FreeResult. */
    *out_buf = batch.buf;
    *out_len = (int32_t)batch.len;
    return VIRTUFIN_STATUS_OK;
}

void FreeResult(uint8_t* result) {
    free(result);
}

Every output needs an id of its own, derived from the input's (here the input's id plus /reply, with the input's id in inputid), so a second delivery of the input produces the same output ids again. An output must not reuse its input's id: a pub/sub broker that drops duplicates by event id takes it for a second copy of the input and drops it, while the publish still reports success. NATS JetStream does this across every topic of a stream, for as long as the stream's duplicate window.

No output is an empty batch, which encodes to zero bytes: return VIRTUFIN_STATUS_OK with *out_buf = NULL. Several outputs are several vf_batch_add calls; the Runtime publishes them in order, each to its own publishtopic (else its ce-type). The complete example is examples/native-worker-c/hello.c.

3. Add a <virtufin*> extension to the nuspec

The engine reads Virtufin-specific metadata from virtufin* elements in the worker's .nuspec (lives inside <metadata>):

<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
  <metadata>
    <id>Virtufin.Worker.MyWorker</id>
    <version>0.0.1</version>
    <authors>...</authors>
    <description>...</description>
    <!-- Virtufin extensions (all optional; defaults shown). -->
    <virtufinAbiVersion>2</virtufinAbiVersion>
    <virtufinEntryPoint>Process</virtufinEntryPoint>
    <virtufinFreeResult>FreeResult</virtufinFreeResult>
    <virtufinLibrary>myworker</virtufinLibrary>
  </metadata>
</package>
Element Required Default Notes
<id> yes — Standard NuGet id. Used as fallback for virtufinLibrary.
<version> yes — Standard NuGet version. Informational.
virtufinAbiVersion no 2 Integer. The engine supports { 2 }; any other value is rejected at load.
virtufinLibrary no <id> Library basename (no extension, no lib prefix). Must match [A-Za-z0-9_.-]+, no .., length ≤ 128.
virtufinEntryPoint no Process The name of the exported function the engine calls.
virtufinFreeResult no FreeResult The name of the exported function that releases the result buffer.

4. Build per-architecture

The worker nupkg follows the standard NuGet convention: runtimes/<rid>/native/<file>. Supported RIDs in v1 are linux-x64 and linux-arm64. The engine looks up the entry whose RID matches RuntimeInformation.RuntimeIdentifier of the running process.

worker.nupkg/
├── Virtufin.Worker.MyWorker.nuspec
└── runtimes/
    └── linux-x64/
        └── native/
            └── libmyworker.so

Build script (Linux x86_64 example, pure-C worker):

#!/usr/bin/env bash
set -euo pipefail
RID="${1:-linux-x64}"
OUT="runtimes/${RID}/native"
mkdir -p "${OUT}"
cc -std=c99 -O2 -fPIC -shared \
   -I. \
   -o "${OUT}/libmyworker.so" \
   myworker.c

# Package as a nupkg. -j flattens the .nuspec into the zip root;
# -r packages the runtimes/ tree recursively.
rm -f worker.nupkg
zip -j worker.nupkg Virtufin.Worker.MyWorker.nuspec >/dev/null
( cd runtimes && zip -r ../worker.nupkg . >/dev/null )

For Windows and macOS support, change the file extension to .dll and .dylib respectively. The engine's LibraryName.BuildFileName derives the right filename per platform.

5. Deploy

Create the worker with mime type application/x-native-dll, inline or from a URL (see the API reference), e.g. with grpcurl:

grpcurl -plaintext -d "{
  \"mime_type\": \"application/x-native-dll\",
  \"topics\": [\"commands.myworker\"],
  \"code_source\": {\"content\": \"$(base64 -i worker.nupkg)\"}
}" localhost:5002 virtufin.WorkManager/CreateWorker

grpcurl -plaintext -d '{"id": "<worker id>"}' localhost:5002 virtufin.WorkManager/StartWorker