docs: state the TLS posture, document the tuning environment variables, and give overload a doc.go - #677
Merged
Conversation
…nt variables (#415, #418) TLS: say plainly that celeris is cleartext by design and TLS terminates at the edge; show the in-process route that works today (std engine + StartWithListener with a tls.NewListener, HTTPS over HTTP/1.1); add what the drivers do when TLS is requested (Postgres ErrSSLNotSupported for require/verify-*, plaintext plus a warning for prefer/allow; Redis rejects rediss://; memcached has no TLS option); point at #446. Environment variables: one table for CELERIS_ADAPTIVE_START, CELERIS_MAX_IOURING_TIER, CELERIS_IOURING_SEND_ZC, CELERIS_IOURING_MULTISHOT_RECV and CELERIS_IOURING_PBUF_COUNT, each as the code reads it at 5b2e83b, plus a do-not-set row for CELERIS_IOURING_FIXED_FILES (#541). CELERIS_ADAPTIVE_START chooses the start engine only; it does not turn off switching, which other docs claim. Feature matrix: provided buffers are only used with multishot recv, and the ring's default size is 1024 per worker (the auto formula's 2 x 20 connections always rounds up to the 1024 minimum), not "auto-scaled".
Every other middleware package keeps its package comment in doc.go. The text is unchanged: go doc -all output is byte-identical before and after, and doc.go plus overload.go reassemble into the original file.
This was referenced Sep 19, 2026
FumingPower3925
added a commit
that referenced
this pull request
Sep 19, 2026
7 of 8 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documentation only, plus moving one package comment into its own file. This covers the README half of #415 and two of #418's three items.
Refs #415, #418
Changes
Engine: celeris.StdplusStartWithListener(tls.NewListener(ln, cfg)). I checked it at 5b2e83b with a throwaway program on the std engine: status 200, HTTP/1.1,c.Scheme() == "https",c.IsTLS() == true.ErrSSLNotSupportedforrequire/verify-ca/verify-full, andprefer/allowconnect in plaintext with a stderr warning (driver/postgres/dsn.goCheckSSL). Redis rejectsrediss://(driver/redis/client.go). Memcached has no TLS option.CELERIS_ADAPTIVE_STARTonly chooses the start engine (chooseStartEngineis its sole reader). It does not turn off switching, although the adaptive package comment and the docs site say it does.CELERIS_MAX_IOURING_TIERtreats any unrecognised value, including a typo, asnone, and atnonethe io_uring engine refuses to start (probe/probe.goparseTierName,engine/iouring/engine.go).CELERIS_IOURING_SEND_ZC=oncannot enable SEND_ZC where the startup probe failed (resolveSendZCPolicy).CELERIS_IOURING_PBUF_COUNTis used only with multishot recv. The code rounds it up to a power of two and clamps it to 1024-32768. The default is effectively 1024: the auto formula is 2 xdefaultConnsPerWorker(20), which is below the 1024 minimum.CELERIS_IOURING_FIXED_FILESgets a do-not-set row (io_uring: fixed-file support is unimplemented behind a malformed accept SQE — readiness checklist before it can be enabled #541).CELERIS_IOURING_MULTISHOT_RECV=1(engine/iouring/worker.go). The ring size is 1024 per worker, not "auto-scaled".middleware/overload/doc.go(Docs gaps: tuning env vars, recovery, overload doc.go #418). This was the only middleware package without one. The move changes no text:go doc -alloutput is byte-identical before and after.Deliberately not in this PR
These wait until the #657 fix PRs have landed, because they touch
adaptive/andengine/iouring/:engine/iouring/doc.gosaysCELERIS_IOURING_PBUF_COUNTvalues "are clamped to [16, 32768]" and that non-power-of-two values "cause ring registration failure". Both are wrong at 5b2e83b: the code rounds up and clamps to [1024, 32768].adaptive.Enginecomment saysCELERIS_ADAPTIVE_START"disables the runtime switch".The docs-site half of #415 and #418 goes to goceleris/docs: the missing
recoveryrow in the middleware catalog, the sameCELERIS_ADAPTIVE_STARTclaim inengines.md, and the std-engine HTTPS route indeployment.md.