Skip to content

Development

Working on virtufin-workers itself. Covers the build pipeline, the test layout, the CI surface, and the contribution conventions.

Build pipeline

The repo has two build entry points: per-worker (the WebSocketManagerController's scripts/build_*.py and scripts/build_both.sh) and shared (@common/scripts/build_*.py).

The shared scripts: - build_managed.py — produces a managed-only nupkg. - build_aot.py — produces an AOT-only nupkg (requires Docker). - publish.py — uploads the nupkg to the Gitea NuGet feed.

The worker-local scripts wrap the shared ones and set the per-worker paths (the managed and AOT csproj locations, the config.json path, the canonical build/ output dir).

The build script is runnable locally: 

# Managed-only
python3 WebSocketManagerController/scripts/build_managed.py

# AOT-only (requires Docker)
python3 WebSocketManagerController/scripts/build_aot.py

# Both (single nupkg with both layouts)
bash WebSocketManagerController/scripts/build_both.sh

The smoke_test_aot.py script verifies the AOT path end-to-end: 

python3 WebSocketManagerController/scripts/smoke_test_aot.py

Tests

WebSocketManagerController/tests/Virtufin.Worker.WebsocketManagerController.Tests/ is a C# xunit test project for the managed path only. It uses a TestData/ProcessAsync/InvalidInputs.json data file (Theory tests) plus a couple of Fact tests for correlationId and replyTopic behavior. The tests instantiate the worker directly and call ProcessAsync.

Note: the test project's <ProjectReference> path is relative to the legacy Virtufin.Worker.WebSocketManagerController path; after the rename to …Managed/, the reference is stale. Update the reference path before running the test project.

The AOT path has no unit tests in this repo (the only test surface is the smoke test, which runs the actual AOT compile). The virtufin-workmanager repo has unit tests for the NativeDllEngine.LoadFromNupkg flow, but those test the engine, not the worker.

CI

/.github/workflows/docs.yaml (calls virtufin-common/.github/workflows/docs-common.yaml@master with docs_repo: virtufin/workers-docs) and /.github/workflows/docs-lint.yaml (calls docs-lint-common.yaml@master) are the two CI surfaces for this repo.

There is no CI workflow for the AOT build smoke test (per the user's explicit decision; the smoke test is a local script in scripts/).

Conventions

  • LIBRARY_VERSION in WebSocketManagerController/config/last_published.version is updated by scripts/publish.py after a successful Gitea upload. The next build's "Version changed" report compares against this file.
  • scripts/build_managed.py and scripts/build_aot.py are thin pass-through wrappers — the real logic is in @common/scripts/build_*.py. The wrapper just sets paths.
  • Both csproj files (Managed/ and Native/) share the same <AssemblyName> so the nupkg's single <virtufinLibrary> value resolves to either the .dll or the .so depending on which engine loads it.
  • The AOT csproj's <Compile Include="..\...Managed\Logic.cs" Link="Logic.cs" /> links the shared handler logic from the managed project dir. Path is relative to the AOT csproj's location, so no absolute paths.
  • NuGet auth is via VIRTUFIN_PACKAGES_USER / VIRTUFIN_PACKAGES_TOKEN env vars; the worker scripts don't read ~/.docker/config.json for NuGet creds (only for Docker). The credentials are provided by the CI runner or the dev shell.

See also

  • Build Script — build_managed.py + build_aot.py + build_both.sh reference
  • Troubleshooting — common build/load failures and how to diagnose them
  • Ecosystem — the wider platform and which docs site covers what