Skip to content

README.md

Latest commit

 

History

History
88 lines (72 loc) · 5.62 KB

README.md

File metadata and controls

88 lines (72 loc) · 5.62 KB
Raw

CWIST Step-by-Step Tutorials

Welcome to the CWIST hands-on tutorial series. Each directory contains a runnable C application (main.c), a build configuration (CMakeLists.txt), and a detailed English guide (README.md).

📚 Complete Tutorial Index

  1. 01-hello-world: Creating a minimal CWIST HTTP web server and registering GET route handlers.
  2. 02-routing-params: Dynamic route parameters (/users/:id) and path variable extraction.
  3. 03-json-api: Building RESTful JSON APIs using cJSON and setting response content headers.
  4. 04-middleware-pipeline: Pipeline middleware registration (cwist_app_use) for global logging and request processing.
  5. 05-database-sqlite: Embedded in-memory SQLite integration, schema creation, and querying.
  6. 06-db-pool: High-concurrency thread-safe SQLite connection pool (cwist_db_pool_t) management.
  7. 07-jwt-auth: Issuing and signing JSON Web Tokens (cwist_jwt_sign) for stateless authentication, releasing the returned token with CWIST_DEFER_FREE.
  8. 08-sse-realtime: Unidirectional real-time event streaming with Server-Sent Events (SSE).
  9. 09-websocket-chat: Full-duplex bidirectional communication with WebSocket handlers.
  10. 10-background-scheduler: Asynchronous task execution with worker thread background schedulers.
  11. 11-csrf-protection: Generating and verifying CSRF defense tokens.
  12. 12-cookie-session: Stateful HTTP cookie and session lifecycle management.
  13. 13-compression-gzip-zstd: Payload compression using Gzip and Zstandard.
  14. 14-metrics-observability: Exposing Prometheus-compatible operational metrics /metrics.
  15. 15-multipart-upload: Parsing multipart/form-data and handling file uploads.
  16. 16-html-builder: Programmatic HTML document tree generation with the HTML builder API.
  17. 17-css-composer: Dynamic CSS stylesheet generation and composition.
  18. 18-healthz-check: Implementing Kubernetes and load balancer /healthz health check endpoints.
  19. 19-post-quantum-tls: Enabling Post-Quantum Hybrid TLS (X25519MLKEM768) powered by BoringSSL.
  20. 20-http3-quic-server: Running HTTP/3 servers over QUIC transport via lsquic.
  21. 21-waf-security: Inspecting request payloads for malicious patterns using built-in WAF rules.
  22. 22-rate-limiting: Protecting endpoints with throughput rate-limiting middleware.
  23. 23-cors-policy: Configuring Cross-Origin Resource Sharing (CORS) response headers.
  24. 24-secure-headers: Hardening web responses with X-Frame-Options and Content Security Policy headers.
  25. 25-big-dumb-reply-cache: Ultra-fast static response caching with the Big Dumb Reply (BDR) engine.
  26. 26-generic-orm: Type-safe generic ORM query building via C11 _Generic macros.
  27. 27-db-migrations: Programmatic database schema migration execution.
  28. 28-transparent-column-encryption: Transparent column-level database encryption (db_crypt), with sealed/opened buffers released via CWIST_DEFER_FREE.
  29. 29-test-client-automation: Writing automated in-memory integration tests with cwist_test_client.
  30. 30-graceful-shutdown: Handling SIGTERM/SIGINT signals for graceful server shutdown, plus cwist_full_gc(true) as its automatic complement.

Memory management: DEFER macros and full-GC auto-rotate

Two ergonomics layers on top of the explicit cwist_alloc/cwist_free model sit behind this series — most tutorials don't need either (see docs/GC.md and cwist/core/mem/alloc.h for the full picture), but two demonstrate them directly:

  • CWIST_DEFER_FREE (a scoped, block-exit cleanup attached to a pointer's declaration — C's practical equivalent of RAII for a value that never leaves the block it's declared in): 07-jwt-auth and 28-transparent-column-encryption.
  • cwist_full_gc(true) (the "auto-rotate" toggle: connections and cwist_alloc blocks a thread/process forgets to release explicitly get swept automatically on thread/process exit, epoch-deferred so a swept connection can never be use-after-freed by a thread still on it): 30-graceful-shutdown.

Both are opt-in and additive — none of the other 27 tutorials' explicit cwist_free()/cwist_app_destroy() calls need to change, and won't behave any differently, whether or not these are used elsewhere in the same process.

🚀 Quick Start

Build any tutorial using CMake:

cd tutorials/01-hello-world
mkdir build && cd build
cmake ..
make
./tut01

Where to go next