## Problem/Motivation ECA has no action to send an HTTP request to an external endpoint. #3316178 pointed to HTTP Client Manager, which needs a Guzzle service description for each endpoint. For ad hoc requests, sites used the "ECA Helper: Http Request" action instead. ECA Helper is unsupported since [SA-CONTRIB-2026-193](https://www.drupal.org/sa-contrib-2026-193), and 332 sites report using it. ECA Remote Request, the other option, is unsupported as well. Those sites need a maintained replacement and a migration path. ## Proposed resolution Add an `eca_http_request` action ("HTTP: send request") to eca_base, built on the core `http_client` service. It supports method, URL, query, headers, a body with a format (raw, JSON, form), authentication (basic, digest), timeout, a small number of retries, maximum response size and a response token. The token keeps the ECA Helper shape (`body`, `json`, `headers`, `status`, `client_error`), so downstream tokens in existing models keep working. Token data must never change the structure of a request. YAML fields go through `eca.service.yaml_parser`, so tokens are replaced inside parsed values, exactly once. Only http and https URLs are accepted, raw Guzzle request options are not exposed, and no field reads or writes a local file. Authentication is a fixed set of choices; the plugin builds the matching Guzzle settings itself. Retries only happen where they cannot process a request twice. A post-update in `eca.post_update.php` rewrites `eca_helper_http_request` actions to the new plugin, in the executable model and in the diagram. `timeout` and basic or digest `auth` move from `request_options` to the new fields. Settings without a safe equivalent (`cookies`, NTLM `auth`, the rest of `request_options`, multipart uploads) are dropped, and the update lists the affected models. ## Remaining tasks - Action plugin with config schema. - Kernel tests with a mocked `http_client`, following `EcaGuideLibrarySourceTest`. - Post-update for ECA Helper models. - Documentation, including how to keep credentials out of the model, how to add NTLM through a core `http_client_middleware` service, and a hint to move slow requests into ECA Queue. ## User interface changes New action "HTTP: send request" in the modeler. ## API changes None. ## Data model changes New config schema for `eca_http_request`. The post-update rewrites existing `eca_helper_http_request` actions in `eca.eca.*` configuration. <details><summary>LLM-summary - Click to expand</summary> ### Background - #3316178 (2022) was resolved through HTTP Client Manager (drupal.org #3316197). Its action executes commands from Guzzle service descriptions, which must be written per endpoint up front. Ad hoc requests composed inside a model are not covered. - ECA Helper (`eca_helper_http_request`) filled that gap. SA-CONTRIB-2026-193 marked the project unsupported and advises uninstalling it. - ECA Remote Request (`eca_remote_request`) is unsupported and marked obsolete. - Some APIs, such as an on-premises Microsoft Dynamics 365 server, enforce NTLM. NTLM is challenge-response based and cannot be expressed as a header. The action does not offer it; see "NTLM" below. ### Plugin - ID `eca_http_request`, label "HTTP: send request", class `Drupal\eca_base\Plugin\Action\HttpRequest`, extends `ConfigurableActionBase`. - Injected services: `http_client`, `http_client_factory`, `http_handler_stack`, `eca.service.yaml_parser`. ### Configuration | Key | Type | Default | Notes | |---|---|---|---| | `method` | string | `get` | `get`, `post`, `put`, `patch`, `delete`, `head` | | `url` | string | `''` | Tokens replaced, then validated: scheme http or https, host required | | `query` | string (YAML) | `''` | Parsed first, then tokens replaced in values | | `headers` | string (YAML) | `''` | Parsed first, then tokens replaced in values | | `body` | string | `''` | Tokens replaced; with `use_yaml`, parsed first | | `use_yaml` | boolean | `FALSE` | Interpret `body` as YAML, same convention as `eca_token_set_value` | | `validate_yaml` | boolean | `FALSE` | Access check fails on invalid YAML, same convention as `eca_token_set_value` | | `body_format` | string | `raw` | `raw`, `json`, `form` | | `auth_type` | string | `none` | `none`, `basic`, `digest` | | `auth_username` | string | `''` | Tokens replaced | | `auth_password` | string | `''` | Tokens replaced | | `timeout` | integer | `30` | Seconds per attempt, Guzzle `timeout` | | `retries` | integer | `0` | 0 to 3 | | `max_response_size` | integer | `1048576` | Bytes | | `token_name` | string | `''` | Response token | ### Execution rules 1. YAML fields are parsed by `YamlParser::parse()` before any token replacement. Tokens are replaced in the parsed values only, and only once. A raw configuration string is never token-replaced before parsing. 2. Parsed YAML fills only its own Guzzle option (`query`, `headers`, `json` or `form_params`). It never reaches the top level of the request options. 3. Request options are built from an allowlist: `query`, `headers`, `body`, `json`, `form_params`, `auth`, `timeout`, `http_errors: FALSE`. Retries use the separate client from rule 10. 4. After token replacement, the URL must use http or https and have a host. Otherwise no request is sent. 5. No option reads from or writes to the local file system. 6. The response body is read as a stream up to `max_response_size`. A larger response is not stored, an error is logged, and `client_error` is 2. 7. Log messages use placeholders. They contain the method and the URL without query string and user info, never the response body or credentials. 8. With `body_format: json`, a string body is decoded with `Json::decode()`. Invalid JSON logs an error, no request is sent, and `client_error` is 2. 9. Authentication: - `basic` uses the Guzzle `auth` option, which sets the `Authorization` header and works with any Guzzle handler. - `digest` uses the Guzzle `auth` option too, which Guzzle implements through cURL options. It therefore needs the PHP cURL extension, which Drupal core does not require. The plugin checks `function_exists('curl_exec')` first. Without it, no request is sent, an error is logged and `client_error` is 2. The configuration form shows a warning in that case. 10. Retries: - With `retries` above 0, a retry middleware is pushed onto a clone of `http_handler_stack`, and the request runs on a separate client from `http_client_factory->fromOptions(['handler' => $stack])`. The shared stack stays untouched. Passing a handler per request is deprecated since Guzzle 7.12, and `RetryMiddleware::exponentialDelay()` since 7.11, so the plugin supplies its own delay function. - A connection failure (`ConnectException`, the request never left) is retried for every method. - Responses with status 429, 502, 503 or 504 are retried only for `get`, `head`, `put` and `delete`, because another method may already have been processed. - The delay is 1, 2 and 4 seconds, or `Retry-After` when present, capped at 5 seconds. - `timeout` applies per attempt, so the worst case is `(retries + 1) * timeout` plus delays. The field description says so. Longer back-off belongs in ECA Queue: check `[name:client_error]` and re-enqueue with "Enqueue a task with a delay" and an attempt counter. ### Credentials Usernames and passwords typed into the action are stored in the model and exported with the configuration. The field descriptions recommend a token instead, for example from "Config: read" with "Include overridden" enabled (its default), so the secret can live in `settings.php`. Developers can also add authentication outside ECA. Core collects services tagged `http_client_middleware` into the `http_client` handler stack (`HandlerStackConfigurator`). A middleware can add authentication for one host with credentials from `settings.php`, without any ECA configuration. ### NTLM NTLM is not part of the action: - Guzzle deprecated the `auth: [user, pass, 'ntlm']` shortcut in 7.12 and removes it in 8.0. Its deprecation message recommends setting the cURL authentication options directly. - Those cURL options need the cURL handler. Passing `curl` options to the stream handler is deprecated since Guzzle 7.11 and rejected in 8.0. - libcurl builds increasingly ship without NTLM. libcurl 8.22.0 in the wodby `drupal-php:8.3` image has none. Sites that need NTLM can add a service tagged `http_client_middleware` that sets `CURLOPT_HTTPAUTH = CURLAUTH_NTLM` and `CURLOPT_USERPWD` for one host, with the credentials from `settings.php`. It applies to every request through `http_client`, including those from this action. ### Response token | Key | Content | |---|---| | `body` | Response body as a string | | `json` | Decoded body, when it is valid JSON | | `headers` | Response headers | | `status` | HTTP status code of the last attempt, 0 when no response was received | | `client_error` | 0: 2xx or 3xx. 1: 4xx, 5xx or transport error. 2: configuration or processing error | Difference from ECA Helper: for 4xx and 5xx, `body` and `headers` carry the real response instead of the exception message. ### Migration from ECA Helper The post-update lives in `eca.post_update.php` because it has to run on every site. It enables eca_base when an affected model exists and the module is off. It works on raw `eca.eca.*` configuration, so it runs whether ECA Helper is still installed or not. Diagram data stored by the Modeler API is updated the same way `_eca_post_update_rename_diagram_form_id()` handles form IDs. | ECA Helper | `eca_http_request` | Notes | |---|---|---| | plugin `eca_helper_http_request` | plugin `eca_http_request` | | | `method` | `method` | Same values | | `url` | `url` | | | `query_parameters` | `query` | | | `headers` | `headers` | | | `data` | `body` | | | `data_yaml` (`yes`, `no`, `1`) | `use_yaml` | | | `data_serialization` `raw`, `json`, `url_encode` | `body_format` `raw`, `json`, `form` | | | `data_serialization` `multipart` | dropped | Model reported | | `cookies` | dropped | Model reported; a `Cookie` header covers simple cases | | `request_options.timeout` | `timeout` | When it is a plain number | | `request_options.auth` | `auth_type`, `auth_username`, `auth_password` | `[user, pass]` becomes `basic`; a third element `basic` or `digest` is kept. A third element `ntlm` is dropped and the model reported. Token strings carry over unchanged, the new fields accept tokens | | other `request_options` keys | dropped | Model reported | | `token_name` | `token_name` | | `request_options` is parsed as YAML without token replacement for this mapping. A value that is not a plain YAML structure is dropped and the model is reported. ### Kernel tests `modules/base/tests/src/Kernel/HttpRequestTest.php`. The `http_client` service is replaced in the container by a client with `MockHandler` and Guzzle history middleware, like `tests/src/Kernel/ProjectBrowserSource/EcaGuideLibrarySourceTest.php`. The retry tests also replace `http_handler_stack` with a stack over the same `MockHandler`, because the retry client is built from it. - A header token value containing YAML syntax (quotes, newline, `key: value`) arrives as one literal header value. The recorded request options contain no extra keys. - A token value containing token syntax is sent literally. - A JSON response is available as `[name:json:key]`. - A 404 response sets `status` 404, `body` from the response, `client_error` 1. - A connection failure sets `status` 0 and `client_error` 1. - `ftp://` and `file://` URLs send no request and set `client_error` 2. - A response above `max_response_size` is not stored and sets `client_error` 2. - `basic` sends an `Authorization` header. `digest` puts the expected `auth` setting into the recorded options. With the cURL extension reported missing, a `digest` request is not sent and `client_error` is 2. The capability check is isolated so the test can force both outcomes. - `retries: 1`: a connection failure followed by 200 ends with status 200 for `post`. A 503 followed by 200 ends with status 200 for `get`, and with status 503 for `post`. `Retry-After: 60` waits no longer than the cap. - Post-update: an ECA Helper model is converted with the mapping above, including `request_options.auth`; an `ntlm` entry is dropped and reported. The diagram matches the executable model, and dropped settings are reported. ### Out of scope - File uploads (multipart). A follow-up could accept a file entity token instead of a path. - NTLM (see "NTLM" above), cookie jars, client certificates and OAuth2 token acquisition. - Asynchronous requests. ECA Queue covers that. </details> AI-Generated: Yes (agent reviewed the ECA Helper, Guzzle and ECA code and drafted this issue summary; reviewed and approved by jurgenhaas).