tools.http_poster module

Universal HTTP request tool supporting any method, headers, cookies, and data.

async tools.http_poster.run(url, method='GET', headers=None, cookies=None, data=None, json_data=None, form_data=None, params=None, timeout=30.0, verify_ssl=True, follow_redirects=True, proxy=None, ctx=None)[source]

Make an arbitrary HTTP request and return the response details.

Entry point for the http_request tool, a general-purpose client supporting any standard method, custom headers/cookies/query params, and a raw, JSON, or form body. It is heavily SSRF-hardened: the target URL is validated and normalized with assert_safe_http_url, outbound headers are sanitized via safe_http_headers, an optional SOCKS5 proxy is checked with assert_safe_socks_proxy_url, and the request itself runs through safe_httpx_client plus safe_http_request (from tools._safe_http), which re-validates redirect hops. Disabling TLS verification is privileged: verify_ssl=False is honored only when the caller holds UNSANDBOXED_EXEC (checked via tools.alter_privileges.has_privilege against the Redis-backed store), otherwise it is forced back on. At most one body type may be supplied, and the timeout is clamped to 1-300 seconds.

Dispatched by the tool runner in tools/__init__.py, which calls this module’s run (tool_def.handler(**arguments, ctx=ctx)) for the registered http_request tool; there are no direct internal callers.

Parameters:

  • url (str) – Target URL; must start with http:// or https://.

  • method (str) – HTTP method; validated against VALID_METHODS and upper-cased. Defaults to GET.

  • headers (Optional[str]) – JSON object string of request headers.

  • cookies (Optional[str]) – JSON object string of cookies.

  • data (Optional[str]) – Raw request body sent verbatim.

  • json_data (Optional[str]) – JSON string sent as a JSON body (sets the JSON content type).

  • form_data (Optional[str]) – JSON object string sent as URL-encoded form fields.

  • params (Optional[str]) – JSON object string of URL query parameters.

  • timeout (float) – Request timeout in seconds; clamped to 1-300, default 30.

  • verify_ssl (bool) – Whether to verify TLS certificates; forced True unless the caller has UNSANDBOXED_EXEC.

  • follow_redirects (bool) – Whether redirects are followed (up to 5).

  • proxy (Optional[str]) – Optional validated SOCKS5 proxy URL (socks5/socks5h); omit for a direct connection.

  • ctx – Tool execution context; supplies redis, config, and user_id for the TLS-off privilege check.

Returns:

JSON. On success an object with status_code, headers, body, the final url, and elapsed_ms; on failure an {"error": ..., "details": ...} object (bad input, blocked URL, timeout, connection failure, too many redirects, etc.).

Return type:

str