feat(server): add OSS webclaw-server REST API binary (closes #29)

Self-hosters hitting docs/self-hosting were promised three binaries
but the OSS Docker image only shipped two. webclaw-server lived in
the closed-source hosted-platform repo, which couldn't be opened. This
adds a minimal axum REST API in the OSS repo so self-hosting actually
works without pretending to ship the cloud platform.

Crate at crates/webclaw-server/. Stateless, no database, no job queue,
single binary. Endpoints: GET /health, POST /v1/{scrape, crawl, map,
batch, extract, summarize, diff, brand}. JSON shapes mirror
api.webclaw.io for the endpoints OSS can support, so swapping between
self-hosted and hosted is a base-URL change.

Auth: optional bearer token via WEBCLAW_API_KEY / --api-key. Comparison
is constant-time (subtle::ConstantTimeEq). Open mode (no key) is
allowed and binds 127.0.0.1 by default; the Docker image flips
WEBCLAW_HOST=0.0.0.0 so the container is reachable out of the box.

Hard caps to keep naive callers from OOMing the process: crawl capped
at 500 pages synchronously, batch capped at 100 URLs / 20 concurrent.
For unbounded crawls or anti-bot bypass the docs point users at the
hosted API.

Dockerfile + Dockerfile.ci updated to copy webclaw-server into
/usr/local/bin and EXPOSE 3000. Workspace version bumped to 0.4.0
(new public binary).
This commit is contained in:
Valerio 2026-04-22 12:25:11 +02:00
parent b4bfff120e
commit 2ba682adf3
20 changed files with 1116 additions and 11 deletions

View file

@ -0,0 +1,85 @@
//! POST /v1/batch — fetch + extract many URLs in parallel.
//!
//! `concurrency` is hard-capped at 20 to avoid hammering targets and
//! to bound memory growth for naive callers. For larger batches use
//! the hosted API.
use axum::{Json, extract::State};
use serde::Deserialize;
use serde_json::{Value, json};
use webclaw_core::ExtractionOptions;
use crate::{error::ApiError, state::AppState};
const HARD_MAX_URLS: usize = 100;
const HARD_MAX_CONCURRENCY: usize = 20;
#[derive(Debug, Deserialize, Default)]
#[serde(default)]
pub struct BatchRequest {
pub urls: Vec<String>,
pub concurrency: Option<usize>,
pub include_selectors: Vec<String>,
pub exclude_selectors: Vec<String>,
pub only_main_content: bool,
}
pub async fn batch(
State(state): State<AppState>,
Json(req): Json<BatchRequest>,
) -> Result<Json<Value>, ApiError> {
if req.urls.is_empty() {
return Err(ApiError::bad_request("`urls` is required"));
}
if req.urls.len() > HARD_MAX_URLS {
return Err(ApiError::bad_request(format!(
"too many urls: {} (max {HARD_MAX_URLS})",
req.urls.len()
)));
}
let concurrency = req.concurrency.unwrap_or(5).clamp(1, HARD_MAX_CONCURRENCY);
let options = ExtractionOptions {
include_selectors: req.include_selectors,
exclude_selectors: req.exclude_selectors,
only_main_content: req.only_main_content,
include_raw_html: false,
};
let url_refs: Vec<&str> = req.urls.iter().map(|s| s.as_str()).collect();
let results = state
.fetch()
.fetch_and_extract_batch_with_options(&url_refs, concurrency, &options)
.await;
let mut ok = 0usize;
let mut errors = 0usize;
let mut out: Vec<Value> = Vec::with_capacity(results.len());
for r in results {
match r.result {
Ok(extraction) => {
ok += 1;
out.push(json!({
"url": r.url,
"metadata": extraction.metadata,
"markdown": extraction.content.markdown,
}));
}
Err(e) => {
errors += 1;
out.push(json!({
"url": r.url,
"error": e.to_string(),
}));
}
}
}
Ok(Json(json!({
"total": out.len(),
"completed": ok,
"errors": errors,
"results": out,
})))
}