airvzxf / airvzxf/voxora

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

未关闭
#162 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
engine pending-human phase-7 refactor
主要语言
Rust
星标
0
派生
1
平均合并
11 分钟
30 天内合并 PR
47

描述

## 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).

贡献指南

打开贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。