Skip to content

docs: state the TLS posture, document the tuning environment variables, and give overload a doc.go - #677

Merged
FumingPower3925 merged 2 commits into
mainfrom
docs/418-gaps
Sep 19, 2026
Merged

FumingPower3925 merged 2 commits into
mainfrom
docs/418-gaps

Conversation

@FumingPower3925

Copy link
Copy Markdown
Contributor

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

  • TLS posture (Document the TLS posture #415).
    • The README's TLS line now says celeris is cleartext by design and TLS terminates at the edge.
    • It shows the in-process route that works today: Engine: celeris.Std plus StartWithListener(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.
    • The Database drivers section says what each driver does when TLS is asked for. Postgres returns ErrSSLNotSupported for require/verify-ca/verify-full, and prefer/allow connect in plaintext with a stderr warning (driver/postgres/dsn.go CheckSSL). Redis rejects rediss:// (driver/redis/client.go). Memcached has no TLS option.
    • Both point at TLS: engine-side termination + driver-side #446.
  • Tuning environment variables (Docs gaps: tuning env vars, recovery, overload doc.go #418). A new table under Engine selection lists every tuning variable, as the code reads it at 5b2e83b:
    • CELERIS_ADAPTIVE_START only chooses the start engine (chooseStartEngine is its sole reader). It does not turn off switching, although the adaptive package comment and the docs site say it does.
    • CELERIS_MAX_IOURING_TIER treats any unrecognised value, including a typo, as none, and at none the io_uring engine refuses to start (probe/probe.go parseTierName, engine/iouring/engine.go).
    • CELERIS_IOURING_SEND_ZC=on cannot enable SEND_ZC where the startup probe failed (resolveSendZCPolicy).
    • CELERIS_IOURING_PBUF_COUNT is 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 x defaultConnsPerWorker (20), which is below the 1024 minimum.
    • CELERIS_IOURING_FIXED_FILES gets 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).
  • Feature matrix. Provided buffers are opt-in together with multishot recv: the buffer ring is created only under 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 -all output is byte-identical before and after.

Deliberately not in this PR

These wait until the #657 fix PRs have landed, because they touch adaptive/ and engine/iouring/:

The docs-site half of #415 and #418 goes to goceleris/docs: the missing recovery row in the middleware catalog, the same CELERIS_ADAPTIVE_START claim in engines.md, and the std-engine HTTPS route in deployment.md.

…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.
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.

1 participant