Port Node Red Node

Port a Node-RED node into EdgeLinkd

EdgeLinkd re-implements Node-RED nodes in Rust, and mirrors Node-RED's own mocha spec suite as pytest tests. For the behaviour we support, a node is only done when all three artifacts exist and the coverage checker agrees:

EdgeLinkd is embedded-first, so a node may deliberately support only part of its upstream behaviour. Behaviour we support must match Node-RED exactly; out-of-scope behaviour is still ported as a title and marked @pytest.mark.skip(reason=...) (see step 4). Never ship a half-working option that looks supported — see the design philosophy in AGENTS.md.

Verification is the [✓] "<name>" (n/n) line for the node you touched in python scripts/specs_diff.py <absolute path to 3rd-party/node-red>, plus cargo fmt --check, clippy and the Rust tests. (The checker's own exit code is global — the repo still has nodes with unported specs, so it can be non-zero even when your node is complete.)

Prerequisites

git submodule update --init --recursive     # populates 3rd-party/node-red (v4.0.9)
(cd 3rd-party/node-red && npm install)      # mocha, needed by scripts/specs_diff.py
pip install -r ./tests/requirements.txt     # pytest, pytest-asyncio, pytest-it, pytest-json-report, ...
cargo build --all                           # also builds the edgelink_pymod Python extension

The pytest suite does not run the edgelinkd binary: tests/__init__.py loads target/<EDGELINK_BUILD_TARGET>/<EDGELINK_BUILD_PROFILE>/edgelink_pymod.{pyd,dll,so}, so those two env vars must match the way you built:

$env:EDGELINK_BUILD_TARGET=""; $env:EDGELINK_BUILD_PROFILE="debug"   # default: target/debug
pytest ./tests/nodes/<category>/test_<name>_node.py -v

CI uses cargo build --profile ci --workspace --features full with EDGELINK_BUILD_PROFILE=ci; see .github/workflows/CICD.yml.

Step 1 — Read the two upstream files

For a node whose spec lives in test/nodes/core/<nr_category>/<nn>-<name>_spec.js:

Read the spec first: its describe('...') and it('...') titles are the acceptance criteria and their exact text must be reproduced in Python. Then read the JS implementation for the behaviour (defaults, property names, error paths, edge cases).

The <name> part of the filename is usually the flow-JSON "type" you must register in Rust (16-range.js → "type": "range"); check the .js RED.nodes.registerType(...) call when it differs.

Step 2 — Implement the Rust node

Full skeleton, APIs and conventions: references/rust-node-authoring.md.

1. Add crates/core/src/runtime/nodes/<category>/<name>.rs (use a directory with mod.rs when the node is big, like function/, trigger/, switch/).
2. Declare it in that category's mod.rs (mod <name>;, wrapped in #[cfg(feature = "...")] if the category is feature-gated). Registration itself is automatic: the #[flow_node] macro inventory::submit!s a MetaNode, and RegistryBuilder::with_builtins() picks it up — there is no central node list.
3. Reuse the existing helpers instead of hand-rolling: with_uow for the receive→process→fan-out loop, fan_out_one/fan_out_many for output, evaluate_node_property_value for typed properties, json::deser::* for config fields, report_status/report_error for observability.
4. Add new dependencies behind a Cargo feature in crates/core/Cargo.toml when the node needs one (see nodes_xml, nodes_mqtt, ...).

Step 3 — Rust unit tests (expected for non-trivial logic)

Put them in the same file under #[cfg(test)] mod tests, driven by build_test_engine(json!([...])) + engine.run_once_with_inject(...) / run_once(...). Use #[tokio::test(flavor = "multi_thread", worker_threads = 4)] whenever the flow touches the JS function node or context.* (those paths use block_in_place), plain #[tokio::test] otherwise. Details in the Rust reference.

Rust unit tests are for logic that is awkward to express through flow JSON. The spec port below is what proves Node-RED compatibility — do not skip it.

Step 4 — Port the spec to pytest

Full harness reference: references/python-spec-tests.md.

Create tests/nodes/<category>/test_<name>_node.py:

import pytest
from tests import *

@pytest.mark.describe('range Node')                # == the JS describe(...) title
class TestRangeNode:
    @pytest.mark.asyncio
    @pytest.mark.it('ranges numbers up tenfold')   # == the JS it(...) title, character for character
    async def test_0001(self):
        ...

Rules that the coverage checker enforces:

• @pytest.mark.describe text and @pytest.mark.it text must be identical to the JS ones (mocha fullTitle is describe + " " + it, and specs_diff.py compares those strings, so a typo, a difference in spacing or a smart quote shows up as a gap).
• One Python test per upstream it(). Keep the upstream order and number the test methods (test_0001, test_0002, ...) as the existing files do.
• Every upstream it() gets a title, including the ones we do not support. Mark those @pytest.mark.skip(reason="<feature> is out of scope: <why>"). specs_diff.py collects with -p no:skip, so a skipped test still counts as covered — the reason= string is the only written record of the gap, which is why it is mandatory and has to name the unsupported feature. A skip never means "not fixed yet": never skip a spec for behaviour we claim to support.
• "should be loaded"-style tests are usually ported as a bare pass body.

Drive the node with the helpers from tests/__init__.py (run_single_node_with_msgs_ntimes, run_with_single_node_ntimes, run_flow_with_msgs_ntimes); they build the inject → node → test-once flow for you and return the messages that reached the end of the flow.

Step 5 — Register the pair in scripts/specs_diff.json

Add [<display name>, "nodes/<category>/test_<name>_node.py", "test/nodes/core/<nr_category>/<nn>-<name>_spec.js"] to the matching category (paths are relative to tests/ and to the Node-RED root).

Step 6 — Verify

cargo build --all
pytest ./tests/nodes/<category>/test_<name>_node.py -v

# authoritative coverage check for every registered node; writes the report and
# exits 0 only when the Python suite covers every upstream it().
# Use an ABSOLUTE Node-RED path: the script chdir()s into it before resolving specs.
python scripts/specs_diff.py "$PWD/3rd-party/node-red" -o tests/REDNODES-SPECS-DIFF.md

cargo fmt --check
cargo clippy --all-features --tests --all
cargo test -p edgelink-core           # or: cargo test --workspace --features full

Read the checker's output for your node: [✓] "range" (13/13) means complete, [×] plus - lines list the upstream tests you still owe. Triage rules, the JSON format and the offline fallback script are in references/spec-coverage-audit.md.