Gebweb Manual

Gebweb is an opinionated web framework written entirely in Geblang on top of stdlib/web/*. It targets developers who'd otherwise reach for FastAPI, Symfony, or API Platform: a typed, decorator-driven workflow with automatic OpenAPI 3.1 + SwaggerUI, the repository pattern, constructor-injection DI, JWT / session auth, response caching, and streaming primitives.

This manual combines setup guides and feature references. Read from the beginning for a guided tour, use the chapter list for a specific topic, or search for an API name from the top of any page.

Status

Gebweb is at version 1.8.10. The CHANGELOG.md in the source tree lists every feature shipped to date; this manual documents how to use them.

Start here

  1. Install Gebweb and create a project.
  2. Build a first API with a controller and constructor-injected service.
  3. Understand app construction before mixing auto-discovered controllers with explicit lists.
  4. Test the app and build it for deployment.

For AI agents

A condensed cheatsheet for AI coding agents working in Gebweb apps lives at AGENTS.md. It's denser than this manual, focused on idioms and common pitfalls, and intended to be read once at the start of a session. Point your agent at that file (and at the Geblang language AGENTS.md in the language docs) before asking it to edit code.

Chapters

  1. Getting started - install, hello-world, request lifecycle.
  2. Routing and decorators - @Get / @Post / @Route, path parameters, controller-level prefix.
  3. Parameter binding - path, query, body, raw escape hatch, type coercion.
  4. Responses - automatic JSON wrapping, gebweb.html / gebweb.file / gebweb.stream, HTTP exceptions. 4a. Views and templates - Twig-style templates, inheritance, filters, context injection.
  5. Validation - @Assert.* rules, custom validators, 422 Problem Details responses.
  6. Repositories and @ApiResource - the Repository<T> interface and auto-CRUD wiring.
  7. Dependency injection - the container, lifecycle model, autowiring rules, @Param, interface-typed parameters, testing patterns.
  8. Serialization groups - @Groups, read / write filters, @ApiResource defaults.
  9. Authentication and roles - useAuthenticator, useSessionAuth, JWT helpers, @Auth, @RequiresRole, user injection.
  10. Middleware - cors, securityHeaders, requestId, requestLog, compress, rateLimit, use / before / after.
  11. Caching - useCacheStore, @Cache(ttl, vary), store options.
  12. WebSockets and SSE - @WebSocket, @Sse, streaming responses.
  13. File uploads - multipart parsing, UploadedFile, dict<string, UploadedFile> parameter binding.
  14. OpenAPI and SwaggerUI - auto-generated spec, decorators that shape it, security schemes, SwaggerUI mount.
  15. Testing - TestClient, in-process dispatch, fixtures, integration with test.Test.
  16. The gebweb CLI - new, dev, build, routes, generate, migrate.
  17. Plugins - gebweb.plugin, custom extensions, sibling packages.
  18. Database migrations - gebweb migrate, versioned SQL files, sqlite / postgres / mysql.
  19. Background jobs - @Job handlers, gebweb.enqueue, gebweb worker, retry/backoff, @Scheduled cron + leader election.
  20. Events - @On subscribers, gebweb.publish, synchronous in-process pub/sub.
  21. Mailer - gebweb.Mailable, SMTP / AWS SES / memory / log transports, sync + async send via the worker.
  22. Storage - gebweb.put / get / etc., memory + local-disk + S3 backends, UploadedFile.saveToStorage.
  23. Message brokers - @OnMessage handlers, gebweb.useMessageQueue / useMessageTopic, gebweb.runMessageWorker for RabbitMQ / STOMP / SQS / SNS / Kafka.
  24. CSRF protection - gebweb.useCsrf, @CsrfExempt, the {{ csrf }} view variable, token cookies.
  25. Flash messages - gebweb.flash, session-backed one-shot category-grouped messages rendered as {{ flashes }}.
  26. Forms and rehydration - submitted body + per- field error map preserved across redirect after validation failure, content-negotiated 422 for JSON clients.
  27. Asset pipeline - gebweb.useStaticAssets, content-hash manifest, the asset view filter, dev vs prod mode.
  28. Security headers - gebweb.useSecurity, default header set, CSP with per-request nonce expansion, HSTS opt-in.
  29. LLM integration - gebweb.useLlm, gebweb.llmClient, provider-agnostic chat / embed / image surface across OpenAI, Anthropic, and AWS Bedrock.
  30. services.yaml - config/services.yaml for parameters, services entries, interface bindings, tags, per-env overlays, and the encrypted secrets vault plus gebweb secrets CLI.
  31. Internationalisation - locale negotiation, YAML catalogs, plural-aware lookup, validation localisation, locale-aware number and date formatting.
  32. Multi-tenancy - tenant resolver, typed-parameter injection, tenant_id stamping and query-scoping helpers.
  33. Health checks - @HealthCheck decorator, /healthz and /readyz endpoints, per-probe timeout and aggregation.
  34. OIDC and OAuth2 sign-in - Google, GitHub, and generic OIDC providers, authorization-code-with-PKCE, automatic session establishment.
  35. Outbound webhooks - subscription registry, HMAC-signed delivery through the job queue, configurable retry and dead-letter handling.
  36. Concurrency and shared state - the request-per-goroutine model, what is shared vs per-request, and using store.Store for safe shared mutable state.
  37. Dev profiler bar - useProfilerBar, the collapsible toolbar injected into HTML responses, time / memory / request panels, and the recordTiming timeline.
  38. Deployment - gebweb.cli standard server entrypoint: flag/env/opts precedence, LetsEncrypt and self-signed HTTPS, graceful drain on SIGINT/SIGTERM.

Conventions

  • All code samples assume import gebweb; at the top of the file.
  • Sub-modules are imported with their natural alias when needed (e.g. import gebweb.errors as errors; for instanceof HttpException checks).
  • "User class" means any class declared in the application's own code - typically a DTO, a domain entity, or the user-injection type the authenticator returns.
Getting started →