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_lazily_described(KIND, descriptor, |doc| {
41        Ok(Arc::new(HttpRequestNode::from_doc(doc)?) as Arc<dyn Node>)
42    });
43}
44
45/// Catalog descriptor of the `http-request` node.
46pub fn descriptor() -> graphrt_core::catalog::NodeDescriptor {
47    use graphrt_core::ValueType;
48    use graphrt_core::catalog::schema::{nested, object, selector, template};
49    use graphrt_core::catalog::{NodeCategory, NodeDescriptor, OutputDescriptor};
50    use serde_json::json;
51
52    let kv_item = nested(json!({ "key": template("Name"), "value": template("Value") }), &["key"]);
53    let kv = json!({
54        "description": "`k: v` lines, a list of {key, value}, or a map; keys and values are templates",
55        "oneOf": [
56            { "type": "string" },
57            { "type": "array", "items": kv_item },
58            { "type": "object", "additionalProperties": { "type": "string" } }
59        ]
60    });
61    let body_item = nested(
62        json!({
63            "key": template("Field name"),
64            "type": { "type": "string", "enum": ["text", "file"] },
65            "value": template("Field value"),
66            "file": selector()
67        }),
68        &[],
69    );
70    NodeDescriptor::new(KIND, "HTTP Request", NodeCategory::Integration)
71        .describe(
72            "Sends an HTTP request through the egress policy (private networks blocked by default, \
73             redirects re-checked, credentials stripped on cross-origin redirects). Non-2xx responses \
74             fail the node unless `fail_on_error_status` is false.",
75        )
76        .icon("globe")
77        .source("graphrt-http")
78        .schema(object(
79            json!({
80                "method": { "type": "string", "default": "get", "description": "HTTP method (case-insensitive)" },
81                "url": template("Request URL"),
82                "headers": kv,
83                "params": kv,
84                "authorization": nested(json!({
85                    "type": { "type": "string", "enum": ["no-auth", "api-key"], "default": "no-auth" },
86                    "config": nested(json!({
87                        "type": { "type": "string", "enum": ["bearer", "basic", "custom"], "default": "bearer" },
88                        "api_key": template("Credential; usually {{#env.NAME#}}"),
89                        "header": { "type": "string", "description": "Header name for `custom`" }
90                    }), &[])
91                }), &[]),
92                "body": nested(json!({
93                    "type": { "type": "string", "enum": ["none", "json", "raw-text", "form-data", "x-www-form-urlencoded", "binary"], "default": "none" },
94                    "data": { "oneOf": [ { "type": "string" }, { "type": "array", "items": body_item } ] }
95                }), &[]),
96                "timeout": nested(json!({
97                    "connect": { "type": "number", "minimum": 0 },
98                    "read": { "type": "number", "minimum": 0 },
99                    "write": { "type": "number", "minimum": 0 },
100                    "max_connect_timeout": { "type": "number", "minimum": 0 },
101                    "max_read_timeout": { "type": "number", "minimum": 0 },
102                    "max_write_timeout": { "type": "number", "minimum": 0 }
103                }), &[]),
104                "ssl_verify": { "type": "boolean", "default": true },
105                "fail_on_error_status": { "type": "boolean", "default": true },
106                "max_response_bytes": { "type": "integer", "minimum": 0 },
107                "retry_non_idempotent": { "type": "boolean", "default": false },
108                "parse_json": { "type": "string", "enum": ["lenient", "strict"], "default": "lenient" }
109            }),
110            &["url"],
111        ))
112        .output(OutputDescriptor::new("status_code", ValueType::Integer))
113        .output(OutputDescriptor::new("body", ValueType::String).describe("Response text (empty for binary bodies)"))
114        .output(OutputDescriptor::new("json", ValueType::Any).describe("Parsed body for JSON responses"))
115        .output(OutputDescriptor::new("headers", ValueType::Object))
116        .output(OutputDescriptor::new("files", ValueType::ArrayFile).describe("Binary response as a file"))
117}