메뉴
Making outgoing HTTP requests from a Rust Golem agent. Use when the user asks to call an external API, make HTTP requests, use an HTTP client, or send HTTP requests from agent code.
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/golemcloud/golem --skill golem-make-http-request-rust명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SOC 직업 분류 기준
SKILL.md 표시 중
| name | golem-make-http-request-rust |
| description | Making outgoing HTTP requests from a Rust Golem agent. Use when the user asks to call an external API, make HTTP requests, use an HTTP client, or send HTTP requests from agent code. |
Golem Rust agents use the wstd crate for outgoing HTTP requests. wstd provides an async HTTP client built on WASI HTTP — it is included by default in every Golem Rust component's Cargo.toml.
⚠️ WARNING: Third-party HTTP client crates like
reqwest,ureq,hyper(client), orsurfwill NOT work in Golem. These crates depend on native networking (tokio, OpenSSL, etc.) which is not available in WebAssembly. Usewstd::httpor another crate that targets the WASI HTTP interface.
use wstd::http::{Client, Request, Body, HeaderValue};
For JSON support (enabled by default via the json feature):
use serde::{Serialize, Deserialize};
// Body::from_json(&T) for serializing request bodies
// response.body_mut().json::<T>() for deserializing response bodies
let request = Request::get("https://api.example.com/data")
.header("Accept", HeaderValue::())
.(Body::())?;
= Client::().(request).?;
= response.().().?;
= ::(body_bytes);
Important: GET requests require an explicit empty body — use
Body::empty()orBody::from(()).
#[derive(Deserialize)]
struct ApiResponse {
id: u64,
name: String,
}
let request = Request::get("https://api.example.com/users/1")
.body(Body::empty())?;
let mut response = Client::new().send(request).await?;
let user: ApiResponse = response.body_mut().json::<ApiResponse>().await?;
#[derive(Serialize)]
struct CreateUser {
name: String,
email: String,
}
let payload = CreateUser {
name: "Alice".to_string(),
email: "alice@example.com".to_string(),
};
// Body::from_json serializes the payload to JSON bytes.
// You must also set the Content-Type header manually.
let request = Request::post("https://api.example.com/users")
.header("Content-Type", "application/json")
.body(Body::from_json(&payload).expect("Failed to serialize"))?;
let mut response = Client::new().send(request).await?;
let request = Request::post("https://api.example.com/submit")
.header("Content-Type", "application/json")
.body(Body::from(r#"{"key": "value"}"#))?;
let mut response = Client::new().send(request).await?;
Body::from converts from &str, String, Vec<u8>, &[u8], and () (empty body).
let request = Request::get("https://api.example.com/secure")
.header("Authorization", HeaderValue::from_static("Bearer my-token"))
.header("Accept", "application/json") // &str works directly
.header("X-Custom", HeaderValue::from_str("dynamic-value")?) // fallible for runtime values
.body(Body::empty())?;
let mut response = Client::new().send(request).await?;
// Status
let status = response.status(); // e.g. StatusCode::OK (200)
// Headers
if let Some(ct) = response.headers().get("Content-Type") {
println!("Content-Type: {}", ct.to_str()?);
}
// Body — choose one:
let bytes = response.body_mut().contents().await?; // &[u8]
// or
let text = response.body_mut().str_contents().await?; // &str
// or (with json feature)
let parsed: MyStruct = response.body_mut().json::<MyStruct>().await?;
wstd::http resolves successfully when the server returns an HTTP response, even if the status
is 500. From Golem's durability point of view, that means the recorded oplog entry already
contains the 500 response, and any subsequent application-level Err/? you produce based on
the status is a separate failure after the side effect.
There are two ways to make Golem retry the HTTP call itself when a non-2xx response arrives.
status-code-keyed retry policyDefine a named retry policy whose predicate explicitly references status-code. When the
response arrives the host transparently re-sends the request — no with_atomic_operation and no
application-level error needed. The resolved Response is the last attempt. See the
golem-retry-policies-rust skill for the policy YAML / SDK shape.
POST/PUT/PATCH work out of the box. Idempotence mode defaults to
true, so a plainPOST /chargewith a body is already eligible for status-code retry — there is no need to wrap the call inwith_idempotence_mode(true, ...). Seegolem-atomic-block-rustfor details on when (rarely) to opt out withwith_idempotence_mode(false, ...).
Minimal POST example — the policy is defined once (in golem.yaml or via the SDK) and the call
site is just a plain HTTP call:
# golem.yaml — under retryPolicyDefaults / <env>:
http-5xx-retry:
priority: 20
predicate:
propIn: { property: "status-code", values: [500, 502, 503, 504] }
policy:
countBox:
maxRetries: 3
inner:
exponential:
baseDelay: "200ms"
factor: 2.0
// Plain POST — no with_atomic_operation, no with_idempotence_mode wrapper.
let request = Request::post("https://payments.example.com/charge")
.header("Content-Type", "application/json")
.body(Body::from_json(&ChargeRequest { order_id, amount })?)?;
let mut response = Client::new().send(request).await?;
if !response.status().is_success() {
// The host already retried up to maxRetries times against the 5xx policy;
// this is the *final* response after retries were exhausted.
return Err(format!("charge failed: {}", response.status()));
}
let charge: ChargeResponse = response.body_mut().json().await?;
If status retry "doesn't seem to work", load the golem-local-dev-server skill and look for the
HTTP status retry skipped, reason: … debug line — it pinpoints why a particular request was
not retried (e.g. BodyNotFinished, NotIdempotent, NoRetry).
When the retry trigger is application-level (e.g. retrying based on a parsed body field, or
combining multiple side effects into one logical step), inspect the response and convert non-2xx
into an Err. Wrap in with_atomic_operation (see golem-atomic-block-rust) if you need recovery
to re-execute the whole request rather than replay the recorded failed response.
let request = Request::get(url).body(Body::empty())?;
match Client::new().send(request).await {
Ok(mut response) => {
if response.status().is_success() {
let data: MyData = response.body_mut().json().await?;
Ok(data)
} else {
let error_body = String::from_utf8_lossy(
response.body_mut().contents().await?
).to_string();
Err(format!("API error {}: {}", response.status(), error_body))
}
}
Err(e) => Err(format!("Request failed: {}", e)),
}
use wstd::http::Client;
use std::time::Duration;
let mut client = Client::new();
client.set_connect_timeout(Duration::from_secs(5));
client.set_first_byte_timeout(Duration::from_secs(10));
client.set_between_bytes_timeout(Duration::from_secs(30));
let response = client.send(request).await?;
use golem_rust::{agent_definition, agent_implementation, endpoint, Schema};
use serde::Deserialize;
use wstd::http::{Client, Body, HeaderValue, Request};
#[derive(Clone, Schema, Deserialize)]
pub struct WeatherReport {
pub temperature: f64,
pub description: String,
}
#[agent_definition(mount = "/weather/{city}")]
pub trait WeatherAgent {
fn new(city: String) -> Self;
#[endpoint(get = "/current")]
async fn get_current(&self) -> WeatherReport;
}
struct WeatherAgentImpl {
city: String,
}
#[agent_implementation]
impl WeatherAgent for WeatherAgentImpl {
fn new(city: String) -> Self {
Self { city }
}
async fn get_current(&self) -> WeatherReport {
let url = format!(
"https://api.weather.example.com/current?city={}",
&self.city
);
let request = Request::get(&url)
.header("Accept", HeaderValue::from_static("application/json"))
.body(Body::empty())
.expect("Failed to build request");
let mut response = Client::new()
.send(request)
.await
.expect("Request failed");
response
.body_mut()
.json::<WeatherReport>()
.await
.expect("Failed to parse response")
}
}
golem-wasi-httpThe golem-wasi-http crate provides a reqwest-inspired API on top of the same WASI HTTP interface, with additional convenience features. Use it with the async and json features:
[dependencies]
golem-wasi-http = { version = "0.2.0", features = ["async", "json"] }
use golem_wasi_http::{Client, Response};
let client = Client::builder()
.default_headers(my_headers)
.connect_timeout(Duration::from_secs(5))
.build()
.unwrap();
// GET with auth
let response = client
.get("https://api.example.com/data")
.bearer_auth("my-token")
.send()
.await
.unwrap();
let data: MyData = response.json().await.unwrap();
// POST with JSON + query params
let response = client
.post("https://api.example.com/users")
.json(&payload)
.query(&[("format", "full")])
.send()
.await
.unwrap();
// Multipart form upload (feature = "multipart")
let form = golem_wasi_http::multipart::Form::new()
.text("name", "file.txt")
.file("upload", path)?;
let response = client.post(url).multipart(form).send().await?;
What golem-wasi-http adds over wstd::http:
.get(), .post(), .bearer_auth(), .basic_auth(), .query(), .form()multipart feature).text() with automatic charset sniffing).error_for_status() to convert 4xx/5xx into errorsCustomRequestExecution for manual control over the WASI HTTP request lifecycle — separate steps for sending the body, firing the request, and receiving the response, useful for streaming large request bodiesresponse.get_raw_input_stream() for direct access to the WASI InputStreamWhen to use wstd::http (default, recommended):
When to use golem-wasi-http:
.bearer_auth(), .query(), .form(), .multipart().error_for_status()Both crates use the same underlying WASI HTTP interface and work correctly with Golem's durable execution.
When making HTTP requests to other Golem agent endpoints (or your own), the request body must match the Golem HTTP body mapping convention: non-binary body parameters are always deserialized from a JSON object where each top-level field corresponds to a method parameter name. This is true even when the endpoint has a single body parameter.
For example, given this endpoint definition:
#[endpoint(post = "/record")]
fn record(&mut self, body: String);
The correct HTTP request must send a JSON object with a body field — not a raw text string:
// ✅ CORRECT — use Body::from_json with a struct whose fields match parameter names
use serde::Serialize;
#[derive(Serialize)]
struct RecordRequest {
body: String,
}
let request = Request::post("http://my-app.localhost:9006/recorder/main/record")
.header("Content-Type", "application/json")
.body(Body::from_json(&RecordRequest { body: "a".to_string() }).unwrap())?;
Client::new().send(request).await?;
// ✅ ALSO CORRECT — inline JSON via raw body string
let request = Request::post("http://my-app.localhost:9006/recorder/main/record")
.header("Content-Type", "application/json")
.body(Body::from(r#"{"body": "a"}"#))?;
Client::new().send(request).await?;
// ❌ WRONG — raw text body does NOT match Golem's JSON body mapping
let request = Request::post("http://my-app.localhost:9006/recorder/main/record")
.header("Content-Type", "text/plain")
.body(Body::from("a"))?;
Rule of thumb: If the target endpoint is a Golem agent, always send
application/jsonwith parameter names as JSON keys. Load thegolem-http-params-rustskill for the full body mapping rules.
wstd::http (async) or golem-wasi-http (reqwest-like; sync by default, async with the async feature) — both target the WASI HTTP interfacereqwest, ureq, hyper (client), surf, and similar crates will NOT work — they depend on native networking stacks (tokio, OpenSSL) unavailable in WebAssemblywasi:http/outgoing-handler) will workwstd::http: GET requests require an explicit body(Body::empty()) callwstd::http: use Body::from_json(&data) to serialize a struct as a JSON request body, and set the Content-Type: application/json header manuallywstd::http: use response.body_mut().json::<T>() to deserialize a JSON response bodywstd is included by default in Golem Rust project templates; golem-wasi-http must be added manually