Parfii-bot 4dfe63b4e2 feat(kei-telegram-webhook): inbound Telegram webhook handler

Sibling to kei-notify-telegram (outbound only). This crate is the inbound
half of the Telegram Bot API integration — receives POST /webhook from
Telegram, verifies secret token, parses Update, emits typed WebhookEvent.

Architecture: handler-only. The crate exposes `handle_webhook` and the
parsed types; the consumer owns the axum::Router and the HTTP server.
This keeps kei-telegram-webhook composable into kei-buddy, kei-gateway,
or any other consumer without forcing a server topology.

Files (9 new, 484 LOC total, all under 200/file):
  * src/update.rs — lean Telegram Update / Message / User / Chat /
    CallbackQuery structs (only fields KeiBuddy needs: chat_id, from,
    text, message_id, date, callback_data; #[serde(default)] on optionals)
  * src/event.rs — WebhookEvent enum (Text / Callback / Other) +
    classify(update) -> WebhookEvent
  * src/handler.rs — axum handler with X-Telegram-Bot-Api-Secret-Token
    header verification (mismatch → 401)
  * src/context.rs — WebhookContext trait (consumer provides
    secret_token() + on_event())
  * src/error.rs — WebhookError via thiserror
  * src/lib.rs — module declarations + re-exports
  * Cargo.toml — workspace member, maturity = "alpha"
  * README.md — usage example (axum Router mount, 10-line snippet)

Tests (5 in src/event.rs + src/handler.rs, all pass):
  * classify_text_message — text Update → WebhookEvent::Text
  * classify_callback_query — callback Update → WebhookEvent::Callback
  * classify_other_returns_other — edited_message-only Update → Other
  * bad_secret_token_returns_401 — wrong header → 401 UNAUTHORIZED
  * good_secret_token_returns_200 — matching header → 200 OK

Verify-before-commit (RULE 0.13 §):
  * cargo check --offline -p kei-telegram-webhook: PASS
  * cargo test --offline -p kei-telegram-webhook --lib: 5 passed / 0 failed
  * cargo check --workspace --offline: PASS (no new warnings)

STATUS-TRUTH from agent: shipped=functional, stubs=0, behaviour-verified=yes.

Follow-up (deferred, not blocking):
  * axum is direct dep "0.7" in this crate + kei-cortex + kei-forge —
    workspace should adopt axum in [workspace.dependencies] for version
    unification (separate consolidation wave)
  * Unmodelled Telegram fields (edited_message, inline_query, photo,
    document, reply_markup) — extend when KeiBuddy needs them

2026-05-12 13:33:31 +08:00

1.2 KiB

Raw Blame History

kei-telegram-webhook

Inbound Telegram Bot API webhook handler.
Sibling to kei-notify-telegram (outbound). This crate is the inbound half.

Purpose

Parse Telegram Update payloads arriving via HTTPS POST into typed WebhookEvent values. Secret-token verification included.

Architecture

The crate exposes a single axum handler function and the parsed types. It does not own an axum::Server — that is the consumer's job. Mount handle_webhook into your existing Router.

Usage

use axum::{routing::post, Router};
use kei_telegram_webhook::handle_webhook;

#[derive(Clone)]
struct AppState { token: String }

#[async_trait::async_trait]
impl kei_telegram_webhook::WebhookContext for AppState {
    fn secret_token(&self) -> &str { &self.token }
    async fn on_event(&self, event: kei_telegram_webhook::WebhookEvent) {
        println!("{event:?}");
    }
}

let state = AppState { token: "MY_SECRET".into() };
let app = Router::new()
    .route("/telegram/webhook", post(handle_webhook::<AppState>))
    .with_state(state);
// pass `app` to your axum::serve call

Status

Alpha — handler logic and unit tests pass; real Telegram POST integration verified by the consumer (KeiBuddy).

1.2 KiB Raw Blame History