Skip to main content

asr_core/
serve.rs

1//! The ASR server: one prepared engine, exposed over the OpenAI-compatible
2//! transcription API (`serve-openai-http`).
3//!
4//! [`run`] answers `POST /v1/audio/transcriptions` with the same multipart
5//! shape the `backend-openai-http` client sends, and returns the same
6//! `{"text": ...}` body that client parses (or plain text under
7//! `response_format=text`) — client and server are the two
8//! halves of one protocol, defined once in this crate. A host can point its
9//! existing OpenAI-compatible callers at a locally prepared engine without
10//! any client change. `GET /health` and `GET /v1/models` exist for
11//! orchestration and for clients that list models before they talk.
12//!
13//! `stream=true` answers `text/event-stream`: the `transcript.text.delta`
14//! / `transcript.text.done` / `error` events the client's `HttpResponse::Sse`
15//! mode parses — the same wire for both halves of the protocol. Engines
16//! with an incremental endpoint (streaming zipformer, cloud backends)
17//! emit deltas as the transcription runs; a client disconnect cancels the
18//! session. Engines without one (the offline families) keep the 400
19//! refusal — see [`Transcribe::supports_streaming`].
20//!
21//! The engine face is a trait ([`Transcribe`]) so the handlers test against
22//! a mock without any model files; [`Engine`](crate::Engine) is the
23//! production implementor. The engine is prepared once by the host (the
24//! seconds-to-minutes part, which is the whole point of a server) and
25//! shared across requests: each
26//! request runs its own recognition session through
27//! [`Engine::transcribe`](crate::Engine::transcribe),
28//! bounded by the engine's `max_active_sessions` — a request beyond that
29//! budget is refused with 503, never queued.
30//!
31//! Memory contract: the multipart upload is fully buffered (bounded by
32//! [`ServeOptions::max_body_bytes`], a limit enforced on the body stream
33//! itself, so over-limit uploads are cut off mid-flight) and the decoded
34//! mono f32 result is resident before any session limit applies — the same
35//! decode-layer contract [`crate::audio::decode_audio`] documents; the
36//! per-request budget is enforced twice, cooperatively by the engine's
37//! deadline and forcibly by an HTTP-layer hard wall (the streaming path
38//! has no wall — headers are already sent, so the cooperative deadline
39//! alone bounds it).
40//!
41//! Engine assembly (family detection, model loading) stays with the host:
42//! it prepares an [`Engine`](crate::Engine) from its own model
43//! configuration and hands it
44//! to [`run`] or [`router`].
45
46use serde::{Deserialize, Serialize};
47use serde_json::json;
48use std::net::SocketAddr;
49use std::sync::Arc;
50use std::time::{Duration, Instant};
51
52use axum::extract::{
53    multipart::MultipartError, DefaultBodyLimit, FromRequest, Multipart, Request, State,
54};
55use axum::http::StatusCode;
56use axum::response::sse::{Event, KeepAlive, Sse};
57use axum::response::{IntoResponse, Response};
58use axum::routing::{get, post};
59use axum::{Json, Router};
60use futures::StreamExt;
61
62use crate::{
63    AsrError, AudioBuffer, ErrorKind, SessionFailure, SessionOptions, SessionOutcome,
64    SessionResult, TranscriptSnapshotSink,
65};
66
67pub mod delta;
68use delta::TextDeltaBuilder;
69
70/// The engine face the handlers consume, as a trait so tests (and hosts)
71/// can run the server over a stand-in without any model load;
72/// [`Engine`](crate::Engine) is the production implementor. A host may wrap
73/// `Engine` with metrics,
74/// queueing or retries and serve the wrapper instead.
75pub trait Transcribe: Send + Sync {
76    fn transcribe(
77        &self,
78        buffer: &AudioBuffer,
79        options: SessionOptions,
80        deadline: Instant,
81    ) -> SessionResult;
82
83    /// Whether [`Transcribe::transcribe_streaming`] carries progress for
84    /// this engine. The handler refuses `stream=true` with a 400 up front
85    /// when this is false — a wrapper that does not override the streaming
86    /// face keeps the pre-streaming contract instead of a stream that
87    /// never carries progress. Override both methods together (or
88    /// neither).
89    fn supports_streaming(&self) -> bool {
90        false
91    }
92
93    /// The streaming face `stream=true` requests transcribe through: same
94    /// one-shot upload, plus a sink receiving the full emerging transcript
95    /// each time it changes (a snapshot to overwrite, not a delta —
96    /// see [`TranscriptSnapshotSink`]). The default implementation refuses, so an
97    /// engine that reports [`Transcribe::supports_streaming`] but does not
98    /// override this still fails the request instead of stalling.
99    fn transcribe_streaming(
100        &self,
101        buffer: &AudioBuffer,
102        options: SessionOptions,
103        deadline: Instant,
104        progress: TranscriptSnapshotSink,
105    ) -> SessionResult {
106        let _ = (buffer, options, deadline, progress);
107        Err(Box::new(SessionFailure {
108            error: AsrError::new(
109                ErrorKind::UnsupportedCapability,
110                "serve",
111                "this engine wrapper does not expose streaming progress",
112            ),
113            outcome: SessionOutcome::default(),
114        }))
115    }
116}
117
118impl Transcribe for crate::Engine {
119    fn transcribe(
120        &self,
121        buffer: &AudioBuffer,
122        options: SessionOptions,
123        deadline: Instant,
124    ) -> SessionResult {
125        crate::Engine::transcribe(self, buffer, options, deadline)
126    }
127
128    fn supports_streaming(&self) -> bool {
129        // The dedicated capability flag (not `partial_results`): the two
130        // can diverge for a future backend that reports session partials
131        // without a serve-streamable incremental face, or vice versa.
132        self.capabilities().streaming_transcription
133    }
134
135    fn transcribe_streaming(
136        &self,
137        buffer: &AudioBuffer,
138        options: SessionOptions,
139        deadline: Instant,
140        progress: TranscriptSnapshotSink,
141    ) -> SessionResult {
142        crate::Engine::transcribe_streaming(self, buffer, options, deadline, progress)
143    }
144}
145
146fn default_bind() -> String {
147    "127.0.0.1:8080".to_string()
148}
149
150fn default_max_body_bytes() -> usize {
151    25 * 1024 * 1024
152}
153
154fn default_max_audio_secs() -> u64 {
155    3600
156}
157
158fn default_model_id() -> String {
159    "asr-core".to_string()
160}
161
162fn default_family() -> String {
163    "unknown".to_string()
164}
165
166/// The server's one-time configuration, fixed when the engine is prepared:
167/// `language` is pinned at startup — the engine config cannot switch
168/// languages at runtime, so a request naming a different language is
169/// refused with an explanation rather than silently transcribed under the
170/// wrong one.
171#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
172#[serde(deny_unknown_fields)]
173pub struct ServeOptions {
174    /// Address to listen on (used by [`run`] only), e.g. `127.0.0.1:8080`.
175    #[serde(default = "default_bind")]
176    pub bind: String,
177    /// Request body cap. The multipart upload is fully buffered before any
178    /// check runs, so this is the memory ceiling per in-flight request.
179    /// The default matches the OpenAI API's own 25 MiB transcription
180    /// upload cap; asr-core's client default (24 MiB) fits beneath it.
181    #[serde(default = "default_max_body_bytes")]
182    pub max_body_bytes: usize,
183    /// Decode budget in seconds of audio (measured against 48 kHz, the
184    /// highest supported decode rate): longer uploads are refused with 400
185    /// before the engine sees them.
186    #[serde(default = "default_max_audio_secs")]
187    pub max_audio_secs: u64,
188    /// Per-request hard wall; `None` stretches with the audio length
189    /// (`max(120s, audio_secs * 3)` — local inference usually runs faster
190    /// than real time, so the stretch never bites early).
191    pub timeout_secs: Option<u64>,
192    /// The recognition language pinned by the engine config, if given.
193    pub language: Option<String>,
194    /// Model id reported by `/v1/models` and `/health`.
195    #[serde(default = "default_model_id")]
196    pub model_id: String,
197    /// Engine family name reported by `/health`.
198    #[serde(default = "default_family")]
199    pub family: String,
200}
201
202impl Default for ServeOptions {
203    fn default() -> Self {
204        Self {
205            bind: default_bind(),
206            max_body_bytes: default_max_body_bytes(),
207            max_audio_secs: default_max_audio_secs(),
208            timeout_secs: None,
209            language: None,
210            model_id: default_model_id(),
211            family: default_family(),
212        }
213    }
214}
215
216/// The router over an already-prepared engine. Public so hosts can run the
217/// server inside their own axum app ([`run`] is the batteries-included
218/// listener); `bind` in `options` is only meaningful to `run`.
219pub fn router(engine: Arc<dyn Transcribe>, options: ServeOptions) -> Router {
220    let max_body_bytes = options.max_body_bytes;
221    let state = Arc::new(AppState { engine, options });
222    Router::new()
223        .route("/v1/audio/transcriptions", post(transcriptions))
224        .route("/v1/models", get(models_list))
225        .route("/health", get(health))
226        .layer(DefaultBodyLimit::max(max_body_bytes))
227        .with_state(state)
228}
229
230struct AppState {
231    engine: Arc<dyn Transcribe>,
232    options: ServeOptions,
233}
234
235async fn transcriptions(State(state): State<Arc<AppState>>, req: Request) -> Response {
236    // The extractor's rejection is only the missing/invalid boundary
237    // (a malformed request); size and stream errors surface through the
238    // field reads below, where the 413 mapping lives. The body limit is
239    // not a middleware pass over the buffered request: `Multipart`'s only
240    // constructor wraps the body in a cumulative stream limit, so an
241    // over-limit upload is cut off mid-flight, never fully buffered.
242    let mut multipart = match Multipart::from_request(req, &state).await {
243        Ok(multipart) => multipart,
244        Err(error) => {
245            return error_response(
246                StatusCode::BAD_REQUEST,
247                format!("invalid multipart request: {error}"),
248            )
249        }
250    };
251    let mut file: Option<axum::body::Bytes> = None;
252    let mut language: Option<String> = None;
253    let mut response_format = "json".to_string();
254    let mut stream = false;
255    loop {
256        let field = match multipart.next_field().await {
257            Ok(Some(field)) => field,
258            Ok(None) => break,
259            Err(error) => return multipart_error(&error),
260        };
261        match field.name() {
262            Some("file") => match field.bytes().await {
263                Ok(bytes) => file = Some(bytes),
264                Err(error) => return multipart_error(&error),
265            },
266            Some("language") => match field.text().await {
267                Ok(text) => language = Some(text).filter(|s| !s.trim().is_empty()),
268                Err(error) => return multipart_error(&error),
269            },
270            Some("response_format") => match field.text().await {
271                Ok(text) => response_format = text,
272                Err(error) => return multipart_error(&error),
273            },
274            Some("stream") => match field.text().await {
275                Ok(text) => stream = matches!(text.trim(), "true" | "1"),
276                Err(error) => return multipart_error(&error),
277            },
278            // `model` names a model the server does not select on (the
279            // engine was loaded at startup); `prompt`/`temperature` have
280            // no offline counterpart. Accepted, ignored.
281            _ => {}
282        }
283    }
284    let Some(bytes) = file else {
285        return error_response(
286            StatusCode::BAD_REQUEST,
287            "multipart field 'file' is required",
288        );
289    };
290    if response_format != "json" && response_format != "text" {
291        return error_response(
292            StatusCode::BAD_REQUEST,
293            format!(
294                "unsupported response_format '{response_format}'; only 'json' and \
295                 'text' are supported"
296            ),
297        );
298    }
299    if stream && response_format != "json" {
300        return error_response(
301            StatusCode::BAD_REQUEST,
302            "streaming requires response_format 'json' (SSE data frames carry JSON \
303             events); drop 'stream' or use response_format 'json'",
304        );
305    }
306    if let Some(requested) = &language {
307        match &state.options.language {
308            Some(pinned) if pinned == requested => {}
309            Some(pinned) => {
310                return error_response(
311                    StatusCode::BAD_REQUEST,
312                    format!(
313                        "this server pins language '{pinned}'; the engine cannot \
314                         switch languages at runtime — restart it with language \
315                         '{requested}'"
316                    ),
317                );
318            }
319            None => {
320                return error_response(
321                    StatusCode::BAD_REQUEST,
322                    "this server was started without a pinned language; the engine \
323                     cannot switch languages at runtime — restart it with language \
324                     '<lang>'",
325                );
326            }
327        }
328    }
329    let engine = state.engine.clone();
330    let options = state.options.clone();
331    // Decode first, off the tokio workers: the request budget stretches
332    // with the decoded length, so it does not exist until the audio is
333    // known.
334    let buffer = match tokio::task::spawn_blocking({
335        let options = options.clone();
336        move || decode_upload(&bytes, options.max_audio_secs)
337    })
338    .await
339    {
340        Ok(Ok(buffer)) => buffer,
341        Ok(Err(error)) => {
342            return error_response(
343                StatusCode::BAD_REQUEST,
344                format!("audio decoding failed: {error}"),
345            )
346        }
347        Err(join) => {
348            return error_response(
349                StatusCode::INTERNAL_SERVER_ERROR,
350                format!("decoding task failed: {join}"),
351            )
352        }
353    };
354    let (session_options, budget) = session_plan(&buffer, &options);
355    let deadline = Instant::now() + budget;
356    if stream {
357        // The pre-flight probe (not the trait default's runtime refusal):
358        // engines without an incremental endpoint — the offline families —
359        // keep answering 400 here, as they did before streaming existed.
360        if !state.engine.supports_streaming() {
361            return error_response(
362                StatusCode::BAD_REQUEST,
363                "streaming responses are not supported by this engine (no incremental \
364                 endpoint); drop 'stream' and read the json body",
365            );
366        }
367        return streaming_transcription(state.engine.clone(), buffer, session_options, deadline);
368    }
369    // The budget is enforced twice: the engine checks the deadline
370    // cooperatively, and the HTTP layer holds a hard wall around the
371    // blocking call for engines that never look at it. `spawn_blocking`
372    // work cannot be cancelled, so a hung engine still occupies its
373    // thread until it returns — the wall bounds the request, not the
374    // thread.
375    let outcome = tokio::time::timeout(
376        budget,
377        tokio::task::spawn_blocking(move || {
378            engine
379                .transcribe(&buffer, session_options, deadline)
380                .map(|outcome| outcome.transcript.text())
381                .map_err(|failure| engine_failure(&failure))
382        }),
383    )
384    .await;
385    match outcome {
386        Ok(Ok(Ok(text))) if response_format == "text" => text.into_response(),
387        Ok(Ok(Ok(text))) => Json(json!({ "text": text })).into_response(),
388        Ok(Ok(Err(failure))) => failure_response(failure),
389        Ok(Err(join)) => error_response(
390            StatusCode::INTERNAL_SERVER_ERROR,
391            format!("transcription task failed: {join}"),
392        ),
393        Err(_elapsed) => error_response(
394            StatusCode::GATEWAY_TIMEOUT,
395            format!("transcription exceeded the request budget ({budget:?})"),
396        ),
397    }
398}
399
400/// The `stream=true` half: an SSE response whose data frames carry the
401/// same events asr-core's own SSE client parses — `transcript.text.delta`
402/// per progress snapshot (the delta against the last frame, since the
403/// engine reports snapshots while the wire format is incremental),
404/// `transcript.text.done` with the final text, and `error` — then the
405/// stream ends.
406///
407/// Progress crosses the sync/async boundary through a watch channel, not
408/// an mpsc: `send_replace` never blocks, so a stalled client cannot park
409/// the engine thread — the newest snapshot simply replaces the queued one,
410/// which is what makes the partial display lag behind without delaying
411/// recognition. `is_closed` detects the receiver being dropped: a client
412/// that disconnects fails the sink, the engine cancels its session, and
413/// the watch closing turns the engine call's own outcome into the terminal
414/// frame.
415fn streaming_transcription(
416    engine: Arc<dyn Transcribe>,
417    buffer: AudioBuffer,
418    session_options: SessionOptions,
419    deadline: Instant,
420) -> Response {
421    let (progress_tx, progress_rx) = tokio::sync::watch::channel(String::new());
422    let sink = TranscriptSnapshotSink::new(move |text| {
423        progress_tx.send_replace(text.to_string());
424        !progress_tx.is_closed()
425    });
426    let handle = tokio::task::spawn_blocking(move || {
427        engine
428            .transcribe_streaming(&buffer, session_options, deadline, sink)
429            .map(|outcome| outcome.transcript.text())
430            .map_err(|failure| engine_failure(&failure))
431    });
432    // The JoinHandle rides the unfold state as an Option: the terminal
433    // frame consumes it, so the next poll sees None and the stream ends —
434    // progress frames carry it along untouched.
435    let events = futures::stream::unfold(
436        (Some(handle), progress_rx, TextDeltaBuilder::new()),
437        |(handle, mut progress, mut deltas)| async move {
438            let mut handle = handle;
439            // The previous poll emitted the terminal frame.
440            handle.as_ref()?;
441            let event = loop {
442                // An Err means the engine call has ended (the sender was
443                // dropped) with every value observed — its outcome is the
444                // terminal frame. A pending unseen value resolves Ok first,
445                // so the final delta still precedes done.
446                if progress.changed().await.is_err() {
447                    match handle.take() {
448                        Some(handle) => break terminal_event(handle).await,
449                        None => return None,
450                    }
451                }
452                let snapshot = progress.borrow_and_update().clone();
453                // Snapshot → append-only delta: snapshots that add nothing
454                // expressible (no change, or a revision of sent text) are
455                // skipped — see [`TextDeltaBuilder`].
456                let Some(delta) = deltas.update(&snapshot) else {
457                    continue;
458                };
459                break sse_event("transcript.text.delta", json!({ "delta": delta }));
460            };
461            // `handle` is None only when the terminal frame consumed it.
462            Some((event, (handle, progress, deltas)))
463        },
464    );
465    Sse::new(events.map(Ok::<_, std::convert::Infallible>))
466        .keep_alive(KeepAlive::default())
467        .into_response()
468}
469
470/// The engine call's terminal frame: the final text, or the failure. The
471/// JoinHandle is consumed here — the caller's stream ends right after.
472async fn terminal_event(handle: tokio::task::JoinHandle<Result<String, RequestFailure>>) -> Event {
473    match handle.await {
474        Ok(Ok(text)) => sse_event("transcript.text.done", json!({ "text": text })),
475        Ok(Err(failure)) => sse_event("error", json!({ "message": failure_message(&failure) })),
476        Err(join) => sse_event(
477            "error",
478            json!({ "message": format!("transcription task failed: {join}") }),
479        ),
480    }
481}
482
483/// The error message of a [`RequestFailure`], for SSE `error` frames. The
484/// status code is decided by the caller of [`failure_response`]; here only
485/// the message travels, in the shape asr-core's client surfaces
486/// (`SSE error` plus detail).
487fn failure_message(failure: &RequestFailure) -> String {
488    match failure {
489        RequestFailure::BadRequest(message)
490        | RequestFailure::Busy(message)
491        | RequestFailure::Timeout(message)
492        | RequestFailure::Engine(message) => message.clone(),
493    }
494}
495
496fn sse_event(name: &str, payload: serde_json::Value) -> Event {
497    // The event type travels twice: as the SSE `event:` field and inside
498    // the JSON data. asr-core's own client (like OpenAI's transcription
499    // stream) parses the type out of the JSON `type` field and ignores the
500    // SSE field; both are written so either convention can read a frame.
501    let mut payload = payload;
502    if let Some(object) = payload.as_object_mut() {
503        object.insert("type".to_string(), json!(name));
504    }
505    Event::default().event(name).data(payload.to_string())
506}
507
508/// Why a request's transcription failed, in status-code terms.
509enum RequestFailure {
510    BadRequest(String),
511    Busy(String),
512    Timeout(String),
513    Engine(String),
514}
515
516fn failure_response(failure: RequestFailure) -> Response {
517    match failure {
518        RequestFailure::BadRequest(message) => error_response(StatusCode::BAD_REQUEST, message),
519        RequestFailure::Busy(message) => error_response(StatusCode::SERVICE_UNAVAILABLE, message),
520        RequestFailure::Timeout(message) => error_response(StatusCode::GATEWAY_TIMEOUT, message),
521        RequestFailure::Engine(message) => {
522            error_response(StatusCode::INTERNAL_SERVER_ERROR, message)
523        }
524    }
525}
526
527/// Session options and the request budget for one decoded upload. An
528/// explicit `timeout_secs` is the hard wall — no silent stretching. The
529/// built-in policy stretches with the audio length: audio_secs * 3 keeps
530/// slack for inference of long material and never bites before that
531/// would.
532fn session_plan(buffer: &AudioBuffer, options: &ServeOptions) -> (SessionOptions, Duration) {
533    let audio_secs = buffer.samples.len() as u64 / u64::from(buffer.spec.sample_rate.max(1));
534    let mut session_options = SessionOptions::new(buffer.spec);
535    session_options.max_duration = Duration::from_secs(audio_secs + 60);
536    // Transcripts run orders of magnitude below the session default (8 MiB);
537    // 2 MiB is already generous headroom for an hour of speech.
538    session_options.max_transcript_bytes = 2 * 1024 * 1024;
539    let budget = options.timeout_secs.map_or_else(
540        || Duration::from_secs((audio_secs * 3).max(120)),
541        Duration::from_secs,
542    );
543    (session_options, budget)
544}
545
546/// Why an engine failure maps to which status: Busy is the concurrency
547/// budget (503, never queued), Timeout the deadline (504), InvalidInput a
548/// malformed request (400), everything else the engine's own fault (500).
549fn engine_failure(failure: &SessionFailure) -> RequestFailure {
550    let message = format!("transcription failed: {}", failure.error);
551    match failure.error.kind {
552        ErrorKind::Busy => RequestFailure::Busy(
553            "the server is at its concurrent-session limit; retry later".to_string(),
554        ),
555        ErrorKind::Timeout => RequestFailure::Timeout(message),
556        ErrorKind::InvalidInput => RequestFailure::BadRequest(message),
557        _ => RequestFailure::Engine(message),
558    }
559}
560
561/// The decode layer's input policy for uploads: webm containers are
562/// refused up front (webm audio is opus in practice and symphonia has no
563/// opus decoder — the generic probe error would send callers chasing the
564/// wrong fix), and the decoded buffer must be non-empty and within the
565/// sample budget. The whole decode result is resident in memory before
566/// the budget check runs, so this is a detection, not an allocation guard
567/// (see `audio::decode_audio`'s memory contract).
568fn decode_upload(bytes: &[u8], max_audio_secs: u64) -> Result<AudioBuffer, AsrError> {
569    if is_webm(bytes) {
570        return Err(AsrError::new(
571            ErrorKind::InvalidInput,
572            "serve",
573            "webm audio uses opus, which cannot be decoded here; transcode to \
574             wav, flac or mp3 first",
575        ));
576    }
577    let buffer = crate::audio::decode_audio(bytes)?;
578    if buffer.samples.is_empty() {
579        return Err(AsrError::new(
580            ErrorKind::InvalidInput,
581            "serve",
582            "no audio could be decoded from the input",
583        ));
584    }
585    let max_samples = max_audio_secs.saturating_mul(48_000);
586    if buffer.samples.len() as u64 > max_samples {
587        return Err(AsrError::new(
588            ErrorKind::InvalidInput,
589            "serve",
590            format!(
591                "decoded audio exceeds the sample budget ({max_samples} samples); \
592                 the input is too long for offline decoding"
593            ),
594        ));
595    }
596    Ok(buffer)
597}
598
599/// EBML magic plus the DocType element, matched as an anchored whole:
600/// element ID 0x4282, size vint 0x84 (the DocType for webm is exactly the
601/// four-byte string "webm"), then the string. Searching for the element
602/// rather than the bare string keeps stray header bytes from matching;
603/// matroska/mka files carry "matroska" instead and do not match. A
604/// non-minimal size vint (legal per EBML) — or opus riding in a matroska
605/// container — falls through and gets the generic decode error: correct,
606/// just less specific.
607fn is_webm(bytes: &[u8]) -> bool {
608    if !bytes.starts_with(&[0x1A, 0x45, 0xDF, 0xA3]) {
609        return false;
610    }
611    let head = &bytes[..bytes.len().min(128)];
612    head.windows(7)
613        .any(|w| w == [0x42, 0x82, 0x84, b'w', b'e', b'b', b'm'])
614}
615
616async fn health(State(state): State<Arc<AppState>>) -> Response {
617    Json(json!({
618        "status": "ok",
619        "model": state.options.model_id,
620        "family": state.options.family,
621    }))
622    .into_response()
623}
624
625async fn models_list(State(state): State<Arc<AppState>>) -> Response {
626    Json(json!({
627        "object": "list",
628        "data": [{
629            "id": state.options.model_id,
630            "object": "model",
631            "created": 0,
632            "owned_by": "asr-core",
633        }],
634    }))
635    .into_response()
636}
637
638/// The OpenAI-style error body: any OpenAI-compatible caller that reads
639/// error payloads gets `{"error": {"message": ...}}`. asr-core's own client
640/// only surfaces the status code (and `x-request-id`), so the message is
641/// there for the callers that do look.
642fn error_response(status: StatusCode, message: impl std::fmt::Display) -> Response {
643    let kind = if status.is_client_error() {
644        "invalid_request_error"
645    } else {
646        "server_error"
647    };
648    (
649        status,
650        Json(json!({ "error": { "message": message.to_string(), "type": kind } })),
651    )
652        .into_response()
653}
654
655/// Multipart extraction failures carry their own status: a body over
656/// `DefaultBodyLimit` is 413, everything else a malformed request (400).
657fn multipart_error(error: &MultipartError) -> Response {
658    let status = error.status();
659    let message = if status == StatusCode::PAYLOAD_TOO_LARGE {
660        format!("request body exceeds the server's size limit (max_body_bytes): {error}")
661    } else {
662        format!("invalid multipart request: {error}")
663    };
664    error_response(status, message)
665}
666
667/// Ctrl+C/SIGTERM stop the accept loop; in-flight requests finish first
668/// (axum's graceful shutdown), then the process exits. Only [`run`] shuts
669/// the server down — embedder routers live as long as their owners keep
670/// them.
671async fn shutdown_signal() {
672    let ctrl_c = async {
673        let _ = tokio::signal::ctrl_c().await;
674    };
675    #[cfg(unix)]
676    let sigterm = async {
677        use tokio::signal::unix::{signal, SignalKind};
678        match signal(SignalKind::terminate()) {
679            Ok(mut term) => {
680                term.recv().await;
681            }
682            // Registration failure parks the future forever so the
683            // select still works; the platform keeps its default
684            // disposition then.
685            Err(_) => std::future::pending::<()>().await,
686        }
687    };
688    #[cfg(not(unix))]
689    let sigterm = std::future::pending::<()>();
690    tokio::select! {
691        _ = ctrl_c => {},
692        _ = sigterm => {},
693    }
694}
695
696/// Bind `options.bind` and serve until Ctrl+C/SIGTERM; in-flight requests
697/// finish first (axum's graceful shutdown), then the process exits. The
698/// batteries-included entry point — hosts that compose their own axum app
699/// use [`router`] instead.
700pub async fn run(engine: Arc<dyn Transcribe>, options: ServeOptions) -> Result<(), AsrError> {
701    let address: SocketAddr = options.bind.parse().map_err(|_| {
702        AsrError::new(
703            ErrorKind::InvalidInput,
704            "serve",
705            format!("invalid bind address '{}'", options.bind),
706        )
707    })?;
708    let app = router(engine, options);
709    let listener = tokio::net::TcpListener::bind(address).await.map_err(|e| {
710        AsrError::new(
711            ErrorKind::Io,
712            "serve",
713            format!("cannot bind {address}: {e}"),
714        )
715    })?;
716    axum::serve(listener, app)
717        .with_graceful_shutdown(shutdown_signal())
718        .await
719        .map_err(|e| AsrError::new(ErrorKind::Io, "serve", format!("server error: {e}")))?;
720    Ok(())
721}
722
723#[cfg(test)]
724mod tests;