From 1f34c541b0aa1b9be32e52e4d30276f8199d62d7 Mon Sep 17 00:00:00 2001 From: yhirose Date: Mon, 9 Mar 2026 19:30:18 -0400 Subject: [PATCH] Add more books --- docs-src/config.toml | 10 ++++ docs-src/pages/en/cookbook/index.md | 93 ++++++++++++++++++++++++++++- docs-src/pages/en/index.md | 1 + docs-src/pages/en/llm-app/index.md | 22 +++++++ docs-src/pages/en/tour/index.md | 2 +- docs-src/pages/ja/cookbook/index.md | 93 ++++++++++++++++++++++++++++- docs-src/pages/ja/index.md | 1 + docs-src/pages/ja/llm-app/index.md | 22 +++++++ docs-src/pages/ja/tour/index.md | 2 +- 9 files changed, 238 insertions(+), 8 deletions(-) create mode 100644 docs-src/pages/en/llm-app/index.md create mode 100644 docs-src/pages/ja/llm-app/index.md diff --git a/docs-src/config.toml b/docs-src/config.toml index e708dfc..0573ee0 100644 --- a/docs-src/config.toml +++ b/docs-src/config.toml @@ -14,6 +14,16 @@ label = "Tour" path = "tour/" icon_svg = '' +[[nav]] +label = "Cookbook" +path = "cookbook/" +icon_svg = '' + +[[nav]] +label = "LLM App" +path = "llm-app/" +icon_svg = '' + [[nav]] label = "GitHub" url = "https://github.com/yhirose/cpp-httplib" diff --git a/docs-src/pages/en/cookbook/index.md b/docs-src/pages/en/cookbook/index.md index 700d6ff..c86b173 100644 --- a/docs-src/pages/en/cookbook/index.md +++ b/docs-src/pages/en/cookbook/index.md @@ -1,8 +1,95 @@ --- title: "Cookbook" -order: 1 +order: 0 --- -This section is under construction. +A collection of recipes that answer "How do I...?" questions. Each recipe is self-contained — read only what you need. -Check back soon for a collection of recipes organized by topic. +## Client + +### Basics +- Get the response body as a string / save to a file +- Send and receive JSON +- Set default headers (`set_default_headers`) +- Follow redirects (`set_follow_location`) + +### Authentication +- Use Basic authentication (`set_basic_auth`) +- Call an API with a Bearer token + +### File Upload +- Upload a file as multipart form data (`make_file_provider`) +- POST a file as raw binary (`make_file_body`) +- Send the body with chunked transfer (Content Provider) + +### Streaming & Progress +- Receive a response as a stream +- Use the progress callback (`set_progress`) + +### Connection & Performance +- Set timeouts (`set_connection_timeout` / `set_read_timeout`) +- Set an overall timeout (`set_max_timeout`) +- Understand connection reuse and Keep-Alive behavior +- Enable compression (`set_compress` / `set_decompress`) +- Send requests through a proxy (`set_proxy`) + +### Error Handling & Debugging +- Handle error codes (`Result::error()`) +- Handle SSL errors (`ssl_error()` / `ssl_backend_error()`) +- Set up client logging (`set_logger` / `set_error_logger`) + +## Server + +### Basics +- Register GET / POST / PUT / DELETE handlers +- Receive JSON requests and return JSON responses +- Use path parameters (`/users/:id`) +- Set up a static file server (`set_mount_point`) + +### Streaming & Files +- Stream a large file in the response (`ContentProvider`) +- Return a file download response (`Content-Disposition`) +- Receive multipart data as a stream (`ContentReader`) +- Compress responses (gzip) + +### Handler Chain +- Add pre-processing to all routes (Pre-routing handler) +- Add response headers with a Post-routing handler (CORS, etc.) +- Authenticate per route with a Pre-request handler (`matched_route`) +- Pass data between handlers with `res.user_data` + +### Error Handling & Debugging +- Return custom error pages (`set_error_handler`) +- Catch exceptions (`set_exception_handler`) +- Log requests (Logger) +- Detect client disconnection (`req.is_connection_closed()`) + +### Operations & Tuning +- Assign a port dynamically (`bind_to_any_port`) +- Control startup order with `listen_after_bind` +- Shut down gracefully (`stop()` and signal handling) +- Tune Keep-Alive (`set_keep_alive_max_count` / `set_keep_alive_timeout`) +- Configure the thread pool (`new_task_queue`) + +## TLS / Security + +- Choosing between OpenSSL, mbedTLS, and wolfSSL (build-time `#define` differences) +- Control SSL certificate verification (disable, custom CA, custom callback) +- Use a custom certificate verification callback (`set_server_certificate_verifier`) +- Set up an SSL/TLS server (certificate and private key) +- Configure mTLS (mutual TLS with client certificates) +- Access the peer certificate on the server (`req.peer_cert()` / SNI) + +## SSE + +- Implement an SSE server +- Use event names to distinguish event types +- Handle reconnection (`Last-Event-ID`) +- Receive SSE events on the client + +## WebSocket + +- Implement a WebSocket echo server and client +- Configure heartbeats (`set_websocket_ping_interval`) +- Handle connection close +- Send and receive binary frames diff --git a/docs-src/pages/en/index.md b/docs-src/pages/en/index.md index 6e40db8..b7e5790 100644 --- a/docs-src/pages/en/index.md +++ b/docs-src/pages/en/index.md @@ -19,3 +19,4 @@ Under the hood, it uses blocking I/O with a thread pool. It's not built for hand - [A Tour of cpp-httplib](tour/) — A step-by-step tutorial covering the basics. Start here if you're new - [Cookbook](cookbook/) — A collection of recipes organized by topic. Jump to whatever you need +- [Building a Desktop LLM App](llm-app/) — A hands-on guide to building a desktop app with llama.cpp, step by step diff --git a/docs-src/pages/en/llm-app/index.md b/docs-src/pages/en/llm-app/index.md new file mode 100644 index 0000000..cb70ebe --- /dev/null +++ b/docs-src/pages/en/llm-app/index.md @@ -0,0 +1,22 @@ +--- +title: "Building a Desktop LLM App with cpp-httplib" +order: 0 +--- + +Build an LLM-powered translation desktop app step by step, learning both the server and client sides of cpp-httplib along the way. Translation is just an example — swap it out to build your own summarizer, code generator, chatbot, or any other LLM application. + +## Dependencies + +- [llama.cpp](https://github.com/ggml-org/llama.cpp) — LLM inference engine +- [nlohmann/json](https://github.com/nlohmann/json) — JSON parser (header-only) +- [webview/webview](https://github.com/webview/webview) — WebView wrapper (header-only) +- [cpp-httplib](https://github.com/yhirose/cpp-httplib) — HTTP server/client (header-only) + +## Chapters + +1. **Embed llama.cpp and create a REST API** — Start with a simple API that accepts text via POST and returns a translation as JSON +2. **Add token streaming with SSE** — Stream translation results token by token using the standard LLM API approach +3. **Add model discovery and download** — Use the client to search and download GGUF models from Hugging Face +4. **Add a Web UI** — Serve a translation UI with static file hosting, making the app accessible from a browser +5. **Turn it into a desktop app with WebView** — Wrap the web app with webview/webview to create an Electron-like desktop application +6. **Code reading: llama.cpp's server implementation** — Compare your implementation with production-quality code and learn from the differences diff --git a/docs-src/pages/en/tour/index.md b/docs-src/pages/en/tour/index.md index 572834b..dfa9568 100644 --- a/docs-src/pages/en/tour/index.md +++ b/docs-src/pages/en/tour/index.md @@ -1,6 +1,6 @@ --- title: "A Tour of cpp-httplib" -order: 1 +order: 0 --- This is a step-by-step tutorial that walks you through the basics of cpp-httplib. Each chapter builds on the previous one, so please read them in order starting from Chapter 1. diff --git a/docs-src/pages/ja/cookbook/index.md b/docs-src/pages/ja/cookbook/index.md index 700d6ff..b73da0c 100644 --- a/docs-src/pages/ja/cookbook/index.md +++ b/docs-src/pages/ja/cookbook/index.md @@ -1,8 +1,95 @@ --- title: "Cookbook" -order: 1 +order: 0 --- -This section is under construction. +「〇〇をするには？」という問いに答えるレシピ集です。各レシピは独立しているので、必要なページだけ読めます。 -Check back soon for a collection of recipes organized by topic. +## クライアント + +### 基本 +- レスポンスボディを文字列で取得する / ファイルに保存する +- JSON を送受信する +- デフォルトヘッダーを設定する（`set_default_headers`） +- リダイレクトを追従する（`set_follow_location`） + +### 認証 +- Basic 認証を使う（`set_basic_auth`） +- Bearer トークンで API を呼ぶ + +### ファイル送信 +- ファイルをマルチパートフォームとしてアップロードする（`make_file_provider`） +- ファイルを生バイナリとして POST する（`make_file_body`） +- チャンク転送でボディを送る（Content Provider） + +### ストリーミング・進捗 +- レスポンスをストリーミングで受信する +- 進捗コールバックを使う（`set_progress`） + +### 接続・パフォーマンス +- タイムアウトを設定する（`set_connection_timeout` / `set_read_timeout`） +- 全体タイムアウトを設定する（`set_max_timeout`） +- 接続の再利用と Keep-Alive の挙動を理解する +- 圧縮を有効にする（`set_compress` / `set_decompress`） +- プロキシを経由してリクエストを送る（`set_proxy`） + +### エラー処理・デバッグ +- エラーコードをハンドリングする（`Result::error()`） +- SSL エラーをハンドリングする（`ssl_error()` / `ssl_backend_error()`） +- クライアントにログを設定する（`set_logger` / `set_error_logger`） + +## サーバー + +### 基本 +- GET / POST / PUT / DELETE ハンドラを登録する +- JSON リクエストを受け取り JSON レスポンスを返す +- パスパラメーターを使う（`/users/:id`） +- 静的ファイルサーバーを設定する（`set_mount_point`） + +### ストリーミング・ファイル +- 大きなファイルをストリーミングで返す（`ContentProvider`） +- ファイルダウンロードレスポンスを返す（`Content-Disposition`） +- マルチパートデータをストリーミングで受け取る（`ContentReader`） +- レスポンスを圧縮して返す（gzip） + +### ハンドラチェーン +- 全ルートに共通の前処理をする（Pre-routing handler） +- Post-routing handler でレスポンスヘッダーを追加する（CORS など） +- Pre-request handler でルート単位の認証を行う（`matched_route`） +- `res.user_data` でハンドラ間データを渡す + +### エラー処理・デバッグ +- カスタムエラーページを返す（`set_error_handler`） +- 例外をキャッチする（`set_exception_handler`） +- リクエストをログに記録する（Logger） +- クライアントが切断したか検出する（`req.is_connection_closed()`） + +### 運用・チューニング +- ポートを動的に割り当てる（`bind_to_any_port`） +- `listen_after_bind` で起動順序を制御する +- グレースフルシャットダウンする（`stop()` とシグナルハンドリング） +- Keep-Alive を調整する（`set_keep_alive_max_count` / `set_keep_alive_timeout`） +- マルチスレッド数を設定する（`new_task_queue`） + +## TLS / セキュリティ + +- OpenSSL・mbedTLS・wolfSSL の選択指針（ビルド時の `#define` の違い） +- SSL 証明書の検証を制御する（証明書の無効化・カスタム CA・カスタムコールバック） +- カスタム証明書検証コールバックを使う（`set_server_certificate_verifier`） +- SSL/TLS サーバーを立ち上げる（証明書・秘密鍵の設定） +- mTLS（クライアント証明書による相互認証）を設定する +- サーバー側でピア証明書を参照する（`req.peer_cert()` / SNI） + +## SSE + +- SSE サーバーを実装する +- SSE でイベント名を使い分ける +- SSE の再接続を処理する（`Last-Event-ID`） +- SSE をクライアントで受信する + +## WebSocket + +- WebSocket エコーサーバー／クライアントを実装する +- ハートビートを設定する（`set_websocket_ping_interval`） +- 接続クローズをハンドリングする +- バイナリフレームを送受信する diff --git a/docs-src/pages/ja/index.md b/docs-src/pages/ja/index.md index b301f2f..a9c328c 100644 --- a/docs-src/pages/ja/index.md +++ b/docs-src/pages/ja/index.md @@ -19,3 +19,4 @@ HTTPSも使えます。OpenSSLやmbedTLSをリンクするだけで、サーバ - [A Tour of cpp-httplib](tour/) — 基本を順を追って学べるチュートリアル。初めての方はここから - [Cookbook](cookbook/) — 目的別のレシピ集。必要なトピックから読めます +- [Building a Desktop LLM App](llm-app/) — llama.cpp を組み込んだデスクトップアプリを段階的に構築する実践ガイド diff --git a/docs-src/pages/ja/llm-app/index.md b/docs-src/pages/ja/llm-app/index.md new file mode 100644 index 0000000..9e4c042 --- /dev/null +++ b/docs-src/pages/ja/llm-app/index.md @@ -0,0 +1,22 @@ +--- +title: "Building a Desktop LLM App with cpp-httplib" +order: 0 +--- + +llama.cpp を組み込んだ LLM 翻訳デスクトップアプリを段階的に構築しながら、cpp-httplib のサーバー・クライアント両面の使い方を実践的に学びます。翻訳は一例であり、この部分を差し替えることで要約・コード生成・チャットボットなど自分のアプリに応用できます。 + +## 依存ライブラリ + +- [llama.cpp](https://github.com/ggml-org/llama.cpp) — LLM 推論エンジン +- [nlohmann/json](https://github.com/nlohmann/json) — JSON パーサー（ヘッダーオンリー） +- [webview/webview](https://github.com/webview/webview) — WebView ラッパー（ヘッダーオンリー） +- [cpp-httplib](https://github.com/yhirose/cpp-httplib) — HTTP サーバー/クライアント（ヘッダーオンリー） + +## 章立て + +1. **llama.cpp を組み込んで REST API を作る** — テキストを POST すると翻訳結果を JSON で返すシンプルな API から始める +2. **SSE でトークンストリーミングを追加する** — 翻訳結果をトークン単位で逐次返す LLM API 標準の方式を実装する +3. **モデルの取得・管理機能を追加する** — Hugging Face から GGUF モデルを検索・ダウンロードするクライアント機能を実装する +4. **Web UI を追加する** — 静的ファイル配信で翻訳 UI をホストし、ブラウザから操作できるようにする +5. **WebView でデスクトップアプリ化する** — webview/webview で包み、Electron 的なデスクトップアプリとして動作させる +6. **llama.cpp 本家のサーバー実装をコードリーディング** — 自分で作ったものとプロダクション品質のコードを比較して学ぶ diff --git a/docs-src/pages/ja/tour/index.md b/docs-src/pages/ja/tour/index.md index 29fc328..e003e9e 100644 --- a/docs-src/pages/ja/tour/index.md +++ b/docs-src/pages/ja/tour/index.md @@ -1,6 +1,6 @@ --- title: "A Tour of cpp-httplib" -order: 1 +order: 0 --- cpp-httplibの基本を、順番に学んでいくチュートリアルです。各章は前の章の内容を踏まえて進む構成なので、1章から順に読んでください。