airvzxf / airvzxf/voxora

[deferred] voxora-http: factor shared HTTP utilities out of voxora-minimax when a second HTTP engine crate appears

Geschlossen
#162 1 Kommentar 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
engine pending-human phase-7 refactor
Vorherrschende Sprache
Rust
Sterne
0
Forks
1
Ø Merge
11 Min.
Gemergte PRs (30 T.)
77

Beschreibung

## Why deferred

`voxora-minimax` (EPIC #153) is the first hosted-API engine crate in the voxora workspace. It ships with its own HTTP plumbing inline:

- `ureq` + `rustls` client wrapper
- `multipart/form-data` builder
- WAV header writer (in-memory)
- OpenAI-style error envelope parser
- Bearer-token auth header builder

These utilities live in `voxora-minimax/src/client.rs` and `voxora-minimax/src/wav.rs` (~230 lines total) per YAGNI: factor them out only when a second consumer appears, so the abstraction boundary is shaped by real convergent needs rather than speculative generality.

## Trigger condition

This issue becomes actionable when **any** of the following land (in priority order):

1. A second `voxora-` crate for a hosted API with non-trivial HTTP plumbing (likely candidates: `voxora-deepgram`, `voxora-assemblyai`, `voxora-aws-transcribe`).
2. A consumer of the workspace (e.g. `telora-daemon`) requests runtime engine switching and needs to share HTTP plumbing.
3. The `voxora-minimax` crate's HTTP layer grows past ~400 lines.

## Proposed scope (when triggered)

`voxora-http` (new internal workspace crate, `publish = true` for downstream ecosystem value):

- `pub fn multipart::WavMultipart::new(file_bytes, filename) -> Multipart` builder.
- `pub fn multipart::add_field(mp, name, value)` helper.
- `pub fn client::BearerAgent::new(api_key, timeout) -> ureq::Agent`.
- `pub fn error::OaiError` envelope struct + `pub fn parse_oai_error(body: &[u8]) -> Option` parser.
- `pub fn wav::write_wav_pcm_f32(samples, sample_rate, channels) -> Vec` (move from `voxora-minimax::wav`).
- `pub fn auth::bearer_header(key: &SecretString) -> (&'static str, String)` returning `("Authorization", format!("Bearer {}", key.expose_secret()))`.

Dependencies: same as `voxora-minimax`'s HTTP deps today (`ureq`, `url`, `secrecy`).

## Migration plan (when triggered)

1. Create `voxora-http` with the surface above.
2. Add it to `[workspace.dependencies]` and update `voxora-minimax`'s `Cargo.toml` to depend on it.
3. Replace `voxora-minimax::client` + `voxora-minimax::wav` internals with thin wrappers that delegate to `voxora-http`.
4. Public API of `voxora-minimax` does NOT change.
5. The second HTTP engine crate (`voxora-deepgram`, etc.) builds directly on `voxora-http`.

## Out of scope (handled by other deferred issues)

- Generic multi-provider abstraction (`voxora-openai-asr` or similar). See separate issue.
- SSE streaming support. The first cut is sync `AsrEngine`; `StreamingAsrEngine` lands per-engine when each provider needs it.

## Reference

Plan file: `.kimi-code/sessions/wd_voxora_ebae4026de6d/session_9570e6a8-72b4-423f-94e8-7fc14318d8b1/agents/main/plans/stargirl-ms-marvel-shang-chi.md` §2 (architectural context) + §3 Step 16 (post-release follow-ups).

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Do not start until a listed trigger occurs, such as a second hosted-API engine. Then inspect voxora-minimax/src/client.rs, voxora-minimax/src/wav.rs, and the workspace Cargo.toml, using the proposed voxora-http surface and migration plan as the guide. Done means the shared crate exists, voxora-minimax delegates without public API changes, and the second consumer builds on it.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
rust
Bereich
api, backend, networking
Issue-Typ
Refactoring
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Aktiv
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
25/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.