Skip to content

docs: document v3 migration and v6 beta changes - #80

Open
rustatian wants to merge 18 commits into
masterfrom
release/v3
Open

docs: document v3 migration and v6 beta changes#80
rustatian wants to merge 18 commits into
masterfrom
release/v3

Conversation

@rustatian

@rustatian rustatian commented Sep 6, 2026

Copy link
Copy Markdown
Member

Document the v5-to-v6 plugin migration for the upcoming v3 release on release/v3.

Included Changes

  • Add a migration guide for HTTP middleware order, H2C, logging and rotation, removed RPC codecs/exporters, and TCP default-build removal.
  • Document named Jobs pools, AMQP v2 configuration, the new NSQ driver, and broker/storage fixes.
  • Update gRPC reflection, Temporal worker capabilities, health checks, metrics, and tracing guidance.
  • Cover pool and Goridge changes, the api/api-go/api-plugins split, slog interfaces, and context-aware plugin contracts. Clarify the unchanged Endure and tcplisten requirements.
  • Replace obsolete Velox examples with a pinned v3 development build. Separate untagged PROXY protocol, static caching, pool, and Temporal changes from the selected beta versions.
  • Document current beta limits, including BoltDB named-pool routing, memory expiration, allocation retry, and service restart behavior.
  • Include zstd middleware documentation for feat: add zstd HTTP middleware zstd#1.
  • Correct startup instructions, CORS and upload restrictions, queue and lock guarantees, and PHP/Go API examples.
  • Repair the historical Lambda adapter mapping, execution limits, and bootstrap build.

Closed PRs

rustatian and others added 14 commits February 17, 2026 17:33
Signed-off-by: Valery Piashchynski <piashchynski.valery@gmail.com>
Signed-off-by: Valery Piashchynski <piashchynski.valery@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Valery Piashchynski <piashchynski.valery@gmail.com>
Signed-off-by: Valery Piashchynski <piashchynski.valery@gmail.com>
Signed-off-by: Valery Piashchynski <piashchynski.valery@gmail.com>
Signed-off-by: Valery Piashchynski <piashchynski.valery@gmail.com>
Signed-off-by: Valery Piashchynski <piashchynski.valery@gmail.com>
Signed-off-by: Valery Piashchynski <piashchynski.valery@gmail.com>
Signed-off-by: Valery Piashchynski <piashchynski.valery@gmail.com>
New keys: prefixes, cache_ttl, cache_miss_ttl, cache_max_entries. Refresh the intro for the in-memory metadata/miss caching, the GET/HEAD method gate, and the weak-etag description (size + mtime).
Copilot AI lite review requested due to automatic review settings September 6, 2026 10:54

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

There are a couple of documentation consistency/clarity issues (HTTP zstd page title format and static cache behavior description) that should be corrected to avoid confusing readers.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR consolidates and expands RoadRunner v3-related documentation by adding new docs pages/features (HTTP zstd middleware and gRPC interceptors) and updating existing pages to reflect newer configuration formats and behaviors.

Changes:

  • Added new documentation pages for HTTP zstd middleware and gRPC unary interceptors, and linked them from navigation and existing guides.
  • Reworked AMQP jobs pipeline documentation to describe versioned pipeline config formats (v2 nested exchange/queue vs legacy flat) and added operational notes (read-only RabbitMQ, RPC declaration behavior).
  • Updated HTTP docs to include zstd in the HTTP middleware reference and refreshed static middleware caching/ETag documentation.
File summaries
File Description
SUMMARY.md Adds nav entries for HTTP zstd and gRPC Interceptors.
queues/amqp.md Updates AMQP pipeline config docs (v2 nested format, legacy keys, permissions/RPC notes, migration/next links).
http/zstd.md New page documenting HTTP zstd middleware availability, config, and behavior.
http/static.md Updates static middleware docs with cache/prefix options and corrected ETag behavior description.
http/http.md Adds zstd to the allowed HTTP middleware list and notes build requirement.
grpc/interceptors.md New page documenting interceptor contract, config, ordering, and build examples.
grpc/grpc.md Adds a cross-link to the new interceptors documentation.
Review details
  • Files reviewed: 7/7 changed files
  • Comments generated: 2
  • Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread http/static.md Outdated
can slow down the overall performance by up to `~10%`, because RoadRunner has to check the path for each file request.
The `static` HTTP middleware serves static content using RoadRunner on the main HTTP plugin endpoint.

To avoid a filesystem lookup on every request, the middleware caches file metadata and misses in memory with a short TTL (`10s` by default). A repeated request for the same path is then answered without touching the filesystem, so the overhead of enabling the middleware stays small. The cache trades a few seconds of staleness for that speed: a file added, changed, or removed on disk is picked up within one TTL. Set the TTLs to `0s` to check the filesystem on every request, or run `rr reset static` to flush the cache at once (for example, after a deploy).
Comment thread http/zstd.md
@@ -0,0 +1,52 @@
# HTTP - Zstd middleware
@rustatian rustatian changed the title docs: consolidate v3 release documentation docs: document v3 migration and v6 beta changes Sep 6, 2026
@rustatian rustatian self-assigned this Sep 6, 2026
@rustatian rustatian added the documentation Improvements or additions to documentation label Sep 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants