Provide http_get_flag() accessor for the server quiesce/shutdown flag (httpcgi.h)

[mgrossmann]

Problem

CGI modules need to read the server's quiesce/shutdown state so long-running
handlers can drain promptly at P HTTPD. mvsMF now does this
(mvslovers/mvsmf#179, PR mvslovers/mvsmf#180: the console poll loops check the
flag and return 503 when the server is quiescing).

But struct httpd is opaque to CGIs — httpcgi.h forward-declares it
(typedef struct httpd HTTPD; /* opaque */) and does not expose the flag field
or its masks. So mvsMF reads the flag byte by a hardcoded ABI offset:

#define HTTPD_OFF_FLAG 0x2C            /* httpd/include/httpd.h: volatile UCHAR flag */
*(volatile unsigned char *)((char *)httpd + HTTPD_OFF_FLAG) & (0x40 | 0x80)

This mirrors the existing http_get_httpx(h) idiom (*(HTTPX **)((char *)(h) + 8)),
but offset 0x08 is documented in httpcgi.h as an ABI commitment, whereas
offset 0x2C for flag is not. struct httpd has already churned (unused_1c
"was: FILE *stats"). If any field before flag is reordered or resized, every
CGI that hardcodes 0x2C silently reads the wrong byte — missing shutdown (a
worker parks → the SA03 in #122) or spuriously returning 503 in normal
operation.

Proposal

Publish an ABI-committed accessor in httpcgi.h, alongside http_get_httpx:

/* flag is at offset 0x2C in struct httpd -- ABI commitment (like httpx @ 0x08). */
#define http_get_flag(h)   (*(volatile unsigned char *)((char *)(h) + 0x2C))

#define HTTPD_FLAG_QUIESCE  0x40    /* stop accepting new requests */
#define HTTPD_FLAG_SHUTDOWN 0x80    /* shutting down now           */

(or an equivalent inline/exported function). Then mvsMF drops its local
HTTPD_OFF_FLAG/mask duplication and reads through the committed accessor, so a
future struct httpd layout change updates one place instead of silently
breaking every CGI.

Scope

• include/httpcgi.h: add the accessor + masks, and note the ABI commitment in
  the comment (as offset 0x08 already is).
• No behavior change in httpd itself; consumers migrate opportunistically.

References

• Consumer: console poll loops ignore server quiesce/shutdown and spin without delay mvsmf#179, Honor server quiesce/shutdown in the console poll loops mvsmf#180
• Epic: Epic: v1.0.0 release readiness — console S0C4, worker teardown, recovery exits mvsmf#177
• Existing idiom: http_get_httpx() in include/httpcgi.h

[mgrossmann]

Layout re-checked 2026-07-26 — offset still correct, accessor still absent; the two failure modes, stated explicitly

Tracker pass. Confirming this stays open, Post-v1.0.0, and pinning down the
two silent failure modes so they are on the record individually rather than
implied.

Current state verified against the tree

struct httpd (include/httpd.h:73) today:

00  char        eye[8]
08  HTTPX       *httpx        <- the published 0x08 ABI commitment
0C  HTTPC       **httpc
10  unsigned    addr
14  int         port
18  int         listen
1C  void        *unused_1c    (was: FILE *stats)
20  FILE        *dbg
24  int         tzoffset
28  HTTPC       **busy
2C  volatile UCHAR flag       <- HTTPD_FLAG_QUIESCE 0x40 / HTTPD_FLAG_SHUTDOWN 0x80
2D  volatile UCHAR login

So flag is at 0x2C — mvsMF's hardcoded HTTPD_OFF_FLAG reads the right
byte on the current build, and the quiesce check deployed for mvsmf#179/#180 is
working as intended. This is a latent ABI risk, not a live defect.

include/httpcgi.h still publishes only http_get_httpx(h) at +8
(httpcgi.h:327). There is no http_get_flag() and no
HTTPD_FLAG_QUIESCE / HTTPD_FLAG_SHUTDOWN exposed to CGIs. Unchanged since
this was filed.

The two silent failure modes, mapped to their causes

The description names both outcomes but does not map each to the layout shift
that produces it. Stating them individually, because they fail in opposite
directions and neither announces itself:

1. Stale byte reads with the quiesce bits set → every console request 503s.
If a field before flag is reordered or resized so that 0x2C lands on a byte
whose value has 0x40 or 0x80 on, mvsMF's poll loops conclude the server is
quiescing while it is running normally. Every console request returns 503
from a healthy server. Loud in effect, but with a completely misleading cause —
it presents as an mvsMF console outage, and nothing points at an httpd struct
change.

2. Stale byte reads with the quiesce bits clear → the check is silently
inactive. If 0x2C instead lands on a byte that never has 0x40/0x80 set,
the quiesce check never fires. Normal operation looks perfect, and the fix
for mvsmf#179 is dead code — no error, no log line, nothing. The regression only
surfaces at the next P HTTPD, as a worker parked past quiesce and the SA03
teardown chain from #122 returning. This is the worse of the two: silent in
normal operation, and it re-arms a bug that was signed off as resolved.

Both modes stem from the same root: 0x2C is not a published ABI
commitment, unlike 0x08. struct httpd has already churned once
(unused_1c — "was: FILE *stats"), so the layout is demonstrably not frozen.

Scope unchanged

include/httpcgi.h: add http_get_flag() plus the two masks, documented as an
ABI commitment the way +8 already is. No behaviour change in httpd; consumers
migrate opportunistically and drop their local HTTPD_OFF_FLAG duplication.