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/crawl — synchronous BFS crawl.
//!
//! NOTE: this server is stateless — there is no job queue. Crawls run
//! inline and return when complete. `max_pages` is hard-capped at 500
//! to avoid OOM on naive callers. For large crawls + async jobs, use
//! the hosted API at api.webclaw.io.
use axum::{Json, extract::State};
use serde::Deserialize;
use serde_json::{Value, json};
use std::time::Duration;
use webclaw_fetch::{CrawlConfig, Crawler, FetchConfig};
use crate::{error::ApiError, state::AppState};
const HARD_MAX_PAGES: usize = 500;
#[derive(Debug, Deserialize, Default)]
#[serde(default)]
pub struct CrawlRequest {
pub url: String,
pub max_depth: Option<usize>,
pub max_pages: Option<usize>,
pub use_sitemap: bool,
pub concurrency: Option<usize>,
pub allow_subdomains: bool,
pub allow_external_links: bool,
pub include_patterns: Vec<String>,
pub exclude_patterns: Vec<String>,
}
pub async fn crawl(
State(_state): State<AppState>,
Json(req): Json<CrawlRequest>,
) -> Result<Json<Value>, ApiError> {
if req.url.trim().is_empty() {
return Err(ApiError::bad_request("`url` is required"));
}
let max_pages = req.max_pages.unwrap_or(50).min(HARD_MAX_PAGES);
let max_depth = req.max_depth.unwrap_or(3);
let concurrency = req.concurrency.unwrap_or(5).min(20);
let config = CrawlConfig {
fetch: FetchConfig::default(),
max_depth,
max_pages,
concurrency,
delay: Duration::from_millis(200),
path_prefix: None,
use_sitemap: req.use_sitemap,
include_patterns: req.include_patterns,
exclude_patterns: req.exclude_patterns,
allow_subdomains: req.allow_subdomains,
allow_external_links: req.allow_external_links,
progress_tx: None,
cancel_flag: None,
};
let crawler = Crawler::new(&req.url, config).map_err(ApiError::from)?;
let result = crawler.crawl(&req.url, None).await;
let pages: Vec<Value> = result
.pages
.iter()
.map(|p| {
json!({
"url": p.url,
"depth": p.depth,
"metadata": p.extraction.as_ref().map(|e| &e.metadata),
"markdown": p.extraction.as_ref().map(|e| e.content.markdown.as_str()).unwrap_or(""),
"error": p.error,
})
})
.collect();
Ok(Json(json!({
"url": req.url,
"status": "completed",
"total": result.total,
"completed": result.ok,
"errors": result.errors,
"elapsed_secs": result.elapsed_secs,
"pages": pages,
})))
}