Skip to main content

graphrt_http/
lib.rs

1//! # graphrt-http
2//!
3//! Outbound HTTP for workflows:
4//!
5//! - [`HttpClient`]: a shared client service enforcing an [`EgressPolicy`]
6//!   (SSRF protection, host allow/deny lists, redirect re-validation, response
7//!   size caps, no environment proxies).
8//! - [`HttpRequestNode`]: the `http-request` node.
9//!
10//! ```no_run
11//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
12//! use graphrt_core::{Registry, Services};
13//! use graphrt_http::{EgressPolicy, HttpClient};
14//!
15//! let mut registry = Registry::with_builtins();
16//! graphrt_http::register(&mut registry);
17//! let services = Services::new().with(HttpClient::new(EgressPolicy::default())?);
18//! # let _ = (registry, services);
19//! # Ok(())
20//! # }
21//! ```
22
23mod body;
24mod client;
25mod node;
26mod policy;
27
28mod files;
29pub use client::{ClientError, HttpClient};
30pub use files::HttpFileResolver;
31pub use node::{HttpRequestNode, INLINE_FILE_LIMIT, KIND};
32pub use policy::{EgressError, EgressPolicy, is_public};
33
34use std::sync::Arc;
35
36use graphrt_core::node::{Node, Registry};
37
38/// Register the `http-request` node kind.
39pub fn register(registry: &mut Registry) {
40    registry.register_described(descriptor(), |doc| Ok(Arc::new(HttpRequestNode::from_doc(doc)?) as Arc<dyn Node>));
41}
42
43/// Catalog descriptor of the `http-request` node.
44pub fn descriptor() -> graphrt_core::catalog::NodeDescriptor {
45    use graphrt_core::ValueType;
46    use graphrt_core::catalog::schema::{nested, object, selector, template};
47    use graphrt_core::catalog::{NodeCategory, NodeDescriptor, OutputDescriptor};
48    use serde_json::json;
49
50    let kv_item = nested(json!({ "key": template("Name"), "value": template("Value") }), &["key"]);
51    let kv = json!({
52        "description": "`k: v` lines, a list of {key, value}, or a map; keys and values are templates",
53        "oneOf": [
54            { "type": "string" },
55            { "type": "array", "items": kv_item },
56            { "type": "object", "additionalProperties": { "type": "string" } }
57        ]
58    });
59    let body_item = nested(
60        json!({
61            "key": template("Field name"),
62            "type": { "type": "string", "enum": ["text", "file"] },
63            "value": template("Field value"),
64            "file": selector()
65        }),
66        &[],
67    );
68    NodeDescriptor::new(KIND, "HTTP Request", NodeCategory::Integration)
69        .describe(
70            "Sends an HTTP request through the egress policy (private networks blocked by default, \
71             redirects re-checked, credentials stripped on cross-origin redirects). Non-2xx responses \
72             fail the node unless `fail_on_error_status` is false.",
73        )
74        .icon("globe")
75        .source("graphrt-http")
76        .schema(object(
77            json!({
78                "method": { "type": "string", "default": "get", "description": "HTTP method (case-insensitive)" },
79                "url": template("Request URL"),
80                "headers": kv,
81                "params": kv,
82                "authorization": nested(json!({
83                    "type": { "type": "string", "enum": ["no-auth", "api-key"], "default": "no-auth" },
84                    "config": nested(json!({
85                        "type": { "type": "string", "enum": ["bearer", "basic", "custom"], "default": "bearer" },
86                        "api_key": template("Credential; usually {{#env.NAME#}}"),
87                        "header": { "type": "string", "description": "Header name for `custom`" }
88                    }), &[])
89                }), &[]),
90                "body": nested(json!({
91                    "type": { "type": "string", "enum": ["none", "json", "raw-text", "form-data", "x-www-form-urlencoded", "binary"], "default": "none" },
92                    "data": { "oneOf": [ { "type": "string" }, { "type": "array", "items": body_item } ] }
93                }), &[]),
94                "timeout": nested(json!({
95                    "connect": { "type": "number", "minimum": 0 },
96                    "read": { "type": "number", "minimum": 0 },
97                    "write": { "type": "number", "minimum": 0 },
98                    "max_connect_timeout": { "type": "number", "minimum": 0 },
99                    "max_read_timeout": { "type": "number", "minimum": 0 },
100                    "max_write_timeout": { "type": "number", "minimum": 0 }
101                }), &[]),
102                "ssl_verify": { "type": "boolean", "default": true },
103                "fail_on_error_status": { "type": "boolean", "default": true },
104                "max_response_bytes": { "type": "integer", "minimum": 0 },
105                "retry_non_idempotent": { "type": "boolean", "default": false },
106                "parse_json": { "type": "string", "enum": ["lenient", "strict"], "default": "lenient" }
107            }),
108            &["url"],
109        ))
110        .output(OutputDescriptor::new("status_code", ValueType::Integer))
111        .output(OutputDescriptor::new("body", ValueType::String).describe("Response text (empty for binary bodies)"))
112        .output(OutputDescriptor::new("json", ValueType::Any).describe("Parsed body for JSON responses"))
113        .output(OutputDescriptor::new("headers", ValueType::Object))
114        .output(OutputDescriptor::new("files", ValueType::ArrayFile).describe("Binary response as a file"))
115}