Skip to main content

post_conversion

docspec_http::handlers::conversion

Function post_conversion 

Source 
pub async fn post_conversion(
    request_id: Option<Extension<RequestId>>,
    headers: HeaderMap,
    body: Bytes,
) -> Result<Response<Body>, HttpError>
Expand description

Handle POST /conversion — convert markdown or HTML to BlockNote JSON, HTML, oxa.dev JSON, or Pandoc native.

The input reader is selected by the request’s Content-Type header (see crate::mime_parser::validate_content_type). The output writer is selected by the request’s Accept header (see crate::mime_parser::negotiate_accept).

The request body is buffered, then converted to completion inside spawn_blocking, then returned in a single response. Conversion errors surface as 422 (parse / sink errors) or 500 (finalize errors) before any response body is sent — no truncated 200 OK on failure.

request_id is accepted as Option<Extension<RequestId>> so the handler remains usable for downstream consumers that mount it standalone without the tower_http::request_id::SetRequestIdLayer. When the extension is absent, the request_id field is omitted from the structured conversion_completed event rather than logged as an empty string — “no correlation id supplied” is a distinct state from “supplied empty”. The same treatment applies to trace_id, which is only set when the upstream X-Trace-ID header is present.

Conversion outcome metrics are recorded with intentionally different scopes:

  • docspec_conversions_total and docspec_conversion_duration_seconds are recorded for every request to this endpoint — including early validation failures — so that all outcomes are visible in dashboards.
  • docspec_http_request_body_bytes is recorded only after Content-Type and Accept validation pass and the body is confirmed non-empty.
  • docspec_conversion_output_bytes is recorded only on successful conversions (failed conversions produce no output).

§Errors

Returns HttpError when request headers or body are invalid, the conversion fails, or the response cannot be constructed.