Workspace log follow-ups: tailLines, how-to wording, Coder rate limit

Follow-ups after #148 (workspace log, start, stop subresources). None blocks current use.

tailLines on coderworkspaces/log. Deferred from the Aggregated API: log, start and stop subresources on CoderWorkspace #148 plan. Today callers get the first limitBytes of the build log (default and max 4 MiB) or a follow stream; there is no "last N lines". Needs a bounded design (Coder returns the log from the start, so tailing must read up to the snapshot cap and keep a bounded ring buffer).
How-to wording (docs/how-to/start-stop-workspaces.md):
- "The follow ends when the build ends": a follow also ends at the follow time limit or the byte budget. Link to the log limits in the reference.
- "Unchanged: the workspace is already started or stopped": true only when the latest build of that kind succeeded; after a failed or canceled build, the request queues a new build.
Coder rate limit under log load. Every call uses the operator token, which Coder limits to 512 requests per minute by default (CODER_API_RATE_LIMIT). Under heavy log or list load, Coder's 429 reaches clients. Document the limit next to the log slots, and consider whether the server should return Retry-After from Coder's answer.

Acceptance: each item is either done with tests/docs or closed with a reason.

Owner: maintainer desk. Trigger: item 2 with the next docs change; items 1 and 3 on user demand.

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: medium

Status after #252 (open, not merged yet):

Item 2 (how-to wording): done in 🤖 docs: clarify log follow end and Unchanged, document the Coder rate limit for logs #252. It fixes the follow end and the Unchanged wording in the how-to, the reference and troubleshooting.
Item 3, docs half: done in 🤖 docs: clarify log follow end and Unchanged, document the Coder rate limit for logs #252. The log section documents the Coder rate limit of the operator token, the Coder request count of a log request (2, plus 1 for follow=true unless the existing log reaches a size limit), and that a Coder 429 has no Retry-After. Tests pin the counts and the missing Retry-After.
Still open: item 1, tailLines. This is new API behavior. It needs decisions on how it combines with limitBytes and follow=true, and on what a cut snapshot means for "the last N lines".
Still open: item 3, passing Coder's Retry-After on. *codersdk.Error does not expose response headers. A Retry-After would make client-go retry on its own (up to 10 times by default) against the one operator token that all callers share. Whether that is wanted is a policy choice.

The trigger for both open items stays the same: user demand.

Generated with mux • Model: anthropic:claude-opus-5-5 • Thinking: high

Navigation Menu