Connection nodes speak of listener and sender, and of send_queue_size

mqtt and http take websocket's vocabulary: their Mode is LISTENER/SENDER,
default names read mqtt_listener_… and http_listener_…, and mqtt's
publish_queue_size is send_queue_size. No alias stays behind, so the flow
store rewrites the old setting in every published and draft mqtt node when it
opens, in the same migration as trigger → debounce. Every mqtt and http
setting carries a one-line description for the editor, and the node-types
reference uses one wording for direction and says that an http sender
publishes a JSON object response on its outputs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WgBfkm4rCmtd1T4vHWjEPx
This commit is contained in:
2026-10-15 09:44:22 +02:00
co-authored by Claude Opus 5.5
parent e98808e9d8
commit a1bdae3484
12 changed files with 241 additions and 160 deletions
+53 -38
View File
@@ -1,4 +1,4 @@
"""HTTP nodes: an inbound webhook trigger and an outbound request sender."""
"""HTTP nodes: an inbound webhook listener and an outbound request sender."""
from __future__ import annotations
@@ -81,50 +81,50 @@ def _first_catch_all(app: FastAPI) -> int:
class HttpNode(Node):
"""
HTTP node that can act as a trigger (receiver) or sender based on configuration.
HTTP node that acts as a listener (webhook) or a sender.
This node integrates with FastAPI to either:
- **Trigger mode**: Receive incoming HTTP requests (GET/POST) and inject data
- **Listener**: Receive incoming HTTP requests (GET/POST) and inject data
into the pipeline. Used when ``provides`` is specified but ``requires`` is empty.
- **Sender mode**: Make outgoing HTTP requests with pipeline data. Used when
``requires`` is specified.
- **Sender**: Make outgoing HTTP requests with pipeline data, and publish a
JSON object response on the outputs. Used when ``requires`` is specified.
:param url: The URL endpoint. For trigger mode, this is the route path
(e.g., "/sensors/temperature"). For sender mode, this is the full URL
:param url: The URL endpoint. For a listener, this is the route path
(e.g., "/sensors/temperature"). For a sender, this is the full URL
to send requests to.
:type url: str
:param method: HTTP method - "GET" or "POST".
:type method: Literal["GET", "POST"]
:param requires: Messages required by this node (makes it a sender node).
:param requires: Messages required by this node (makes it a sender).
:type requires: MessageSpec | list[MessageSpec] | None
:param provides: Messages provided by this node (makes it a trigger node).
:param provides: Messages provided by this node (makes it a listener).
:type provides: MessageSpec | list[MessageSpec] | None
:param params: Additional parameters for the node.
:type params: dict
:param name: Optional name for the node.
:type name: str | None
:param timeout: Request timeout in seconds (for sender mode).
:param timeout: Request timeout in seconds (sender only).
:type timeout: float
:param headers: Additional HTTP headers.
:type headers: dict[str, str] | None
:param secret: Shared secret callers append to the webhook URL (trigger mode).
:param secret: Shared secret callers append to the webhook URL (listener only).
:type secret: str
:raises ValueError: If both ``requires`` and ``provides`` are empty, or if
the configuration is invalid.
:example:
Trigger node (receives POST requests):
Listener (receives POST requests):
>>> trigger = HttpNode(
>>> listener = HttpNode(
... url="/api/sensors/temperature",
... method="POST",
... provides=[MessageSpec(name="temperature", dtype=DType.FLOAT)],
... params={},
... )
Sender node (makes POST requests):
Sender (makes POST requests):
>>> sender = HttpNode(
... url="https://api.example.com/data",
@@ -137,7 +137,7 @@ class HttpNode(Node):
class Mode(Enum):
"""Operating mode of the HTTP node."""
TRIGGER = "trigger" # Receives HTTP requests
LISTENER = "listener" # Receives HTTP requests
SENDER = "sender" # Sends HTTP requests
# A repeated request is a repeated request, whatever the endpoint does
@@ -159,14 +159,29 @@ class HttpNode(Node):
class Params(BaseModel):
model_config = ConfigDict(extra="allow")
url: str
method: Literal["GET", "POST"] = "POST"
timeout: float = 30.0
headers: dict[str, str] = {}
url: str = Field(
description=(
"A path such as /tick, served as a webhook at /hooks/<flow>/<path>, "
"or the full URL a sender requests."
)
)
method: Literal["GET", "POST"] = Field(
default="POST",
description="The method a webhook accepts or a sender uses.",
)
timeout: float = Field(
default=30.0, description="Seconds a sender waits for the response."
)
headers: dict[str, str] = Field(
default={},
description=(
"Request headers, sender only. A value may be a secret reference."
),
)
query: dict[str, Any] = Field(
default_factory=dict,
description=(
"Fixed query parameters, sender mode. A value may be a secret "
"Fixed query parameters, sender only. A value may be a secret "
"reference, which is how an API key stays out of the flow file."
),
)
@@ -228,7 +243,7 @@ class HttpNode(Node):
)
# Inputs mean this node sends data out; outputs mean it receives.
self.mode = HttpNode.Mode.SENDER if requires else HttpNode.Mode.TRIGGER
self.mode = HttpNode.Mode.SENDER if requires else HttpNode.Mode.LISTENER
self.url = cfg.url
self.method = cfg.method.upper()
@@ -245,12 +260,12 @@ class HttpNode(Node):
name = f"http_{self.mode.value}_{safe_url}"
# Initialize parent with appropriate function
# For trigger mode, f is a no-op since data is injected via inject()
# For sender mode, f handles the outgoing HTTP request
# For a listener, f is a no-op since data is injected via inject()
# For a sender, f handles the outgoing HTTP request
super().__init__(
f=(
self._noop_trigger
if self.mode == HttpNode.Mode.TRIGGER
self._noop_listener
if self.mode == HttpNode.Mode.LISTENER
else self._sender_handler
),
requires=requires,
@@ -260,11 +275,11 @@ class HttpNode(Node):
)
@staticmethod
def _noop_trigger(params: dict[str, Any], **kwargs: Any) -> dict[str, Any] | None:
def _noop_listener(params: dict[str, Any], **kwargs: Any) -> dict[str, Any] | None:
"""
No-op function for trigger mode nodes.
No-op function for listener nodes.
Trigger mode nodes inject data via :meth:`inject`, not :meth:`__call__`.
Listener nodes inject data via :meth:`inject`, not :meth:`__call__`.
This function exists only to satisfy the Node interface.
"""
return None
@@ -273,7 +288,7 @@ class HttpNode(Node):
self, params: dict[str, Any], **kwargs: Any
) -> dict[str, Any] | None:
"""
Send HTTP request with pipeline data (sender mode).
Send HTTP request with pipeline data (sender).
This method is called when upstream dependencies are satisfied.
It sends the required data via HTTP request.
@@ -332,37 +347,37 @@ class HttpNode(Node):
async def start(self, app: FastAPI | None = None) -> None:
"""A webhook needs a route; a sender reaches out on its own."""
if self.mode is HttpNode.Mode.TRIGGER and app is not None:
if self.mode is HttpNode.Mode.LISTENER and app is not None:
self.register_route(app)
async def stop(self, app: FastAPI | None = None) -> None:
if self.mode is HttpNode.Mode.TRIGGER and app is not None:
if self.mode is HttpNode.Mode.LISTENER and app is not None:
self.unregister_route(app)
def register_route(self, app: FastAPI) -> None:
"""
Register this node's HTTP endpoint with a FastAPI application.
This method should only be called for trigger mode nodes. It creates
This method should only be called for listener nodes. It creates
a route that, when called, triggers the node in the pipeline.
:param app: The FastAPI application instance.
:type app: FastAPI
:raises RuntimeError: If called on a sender mode node.
:raises RuntimeError: If called on a sender.
:example:
>>> from fastapi import FastAPI
>>> app = FastAPI()
>>> trigger_node = HttpNode(
>>> listener = HttpNode(
... url="/sensors/data",
... method="POST",
... provides=[MessageSpec(name="value", dtype=DType.FLOAT)],
... params={},
... )
>>> trigger_node.register_route(app)
>>> listener.register_route(app)
"""
if self.mode != HttpNode.Mode.TRIGGER:
raise RuntimeError("Can only register routes for trigger mode nodes")
if self.mode != HttpNode.Mode.LISTENER:
raise RuntimeError("Can only register routes for listener nodes")
if self._route_registered:
return
@@ -408,7 +423,7 @@ class HttpNode(Node):
if spec.port in data:
typed_data[spec.port] = spec.coerce(data[spec.port])
# Inject data into the pipeline (trigger mode nodes inject via
# Inject data into the pipeline (listener nodes inject via
# provides). Off the loop: journalling is a blocking Redis
# round trip, and every webhook was making it on the thread
# the whole API answers from.