[aberoham]

teams listen printed every notification posted to it without checking clientState, listened on every interface, had no size or time limits, and held Graph's response until stdout took the line. This makes it safe to run behind a tunnel or relay.

Behaviour changes:

• The default bind is now 127.0.0.1. Use --bind 0.0.0.0 to accept other hosts.
• --client-state (or TEAMS_CLI_CLIENT_STATE) drops notifications that don't match. Without it, startup warns that notifications are unauthenticated.
• Notifications get 202 once queued, not 200 after printing. A full queue, or shutdown, returns 503.
• Bodies over 1 MiB get 413. Headers and bodies have 10 s each; at most 64 connections are served.
• Output lines keep every field Graph sends, add kind (change or lifecycle), and no longer include clientState.
• Ctrl+C writes out everything already acknowledged; a second signal abandons it, and lost lines exit 1.
• A port in use is CONFIG_ERROR (exit 10), not AUTH_FAILED (exit 3).
• Logs are coloured only when stderr is a terminal and NO_COLOR is unset or empty.
• subscribe create --lifecycle-url sets lifecycleNotificationUrl, which Graph requires for Teams subscriptions over an hour.

Review guide:

• cbbf73a --lifecycle-url.
• c95b22c the listener. The parts worth most attention are the filtering and response codes in src/listen/handler.rs.
• decc906 shutdown. Check the acknowledgement accounting in src/listen/queue.rs.
• 011fa39 log colour.

Testing: tests/listen.rs runs the real binary over sockets, including a stdout reader that stops reading (503, validation still answers) and SIGINT with a backlog. Also run locally against curl.

https://claude.ai/code/session_01Hd5XXx9UkpLZpAAkvPPyUg

[sionsmith]

[P1] Persist accepted notifications before returning 202

src/listen/handler.rs returns 202 after Queue::try_push, but src/listen/queue.rs stores the only pending copy in an in-memory channel. This adds a crash-loss window for notifications the sender considers delivered. Graceful shutdown accounting cannot recover from SIGKILL, a process crash, or a host restart.

Reproduced on PR head 011fa39 using the real binary: start listen --port 0 --client-state review-secret with stdout piped and deliberately unread; POST six valid notification collections, each with a 512 KiB resourceData field. All six requests return 202. Kill the process with SIGKILL and drain stdout: zero complete NDJSON lines (only a partial first line), leaving all six acknowledged notifications unavailable. Restart has no spool to recover.

Perplexity cross-check and the primary Microsoft documentation confirm that Graph treats a 2xx response as delivered, and recommends validating and persisting notifications before returning 202. A relay following this PR's response table also stops retrying after 202.

Please retain accepted events durably before acknowledgement and recover/replay pending events after restart. Test a blocked stdout consumer followed by forced process death and restart. Duplicate delivery can still occur around the output/checkpoint boundary; document that separately. If the intended product is instead a lossy development stream, make the durability limitation an explicit design decision and revise the relay-safety claims before merging.

Source: https://learn.microsoft.com/en-us/graph/change-notifications-delivery-webhooks#http-codes-and-retry-logic

The existing formatting, check, Clippy and test suites pass locally and in Linux/macOS/Windows CI; those successful checks do not cover this crash case. Leaving this PR unmerged on this finding.

[sionsmith]

Thanks @aberoham, this is thorough work. Here's what I verified and what I added.

Reproduced on main by running the real binary against curl:

• It listened on *:port.
• It printed a forged notification, plus the real clientState secret.
• It read a 2 MiB body to the end before answering 400.
• A port in use gave AUTH_FAILED (exit 3).
• Redirected stderr carried ANSI codes.
• subscriptionExpirationDateTime was dropped.

Verified on this branch. All of those are fixed:

• It binds 127.0.0.1.
• The forged post gets 202 but is dropped, with a warning that contains neither secret.
• The genuine line keeps every Graph field, adds kind, and omits clientState.
• 2 MiB gets 413, and the port in use gives CONFIG_ERROR (exit 10).

The response codes match Microsoft's webhook guidance:

• 202 for accepted notifications, within 3 s.
• Validation echoed as text/plain within 10 s.
• A mismatched clientState is discarded but still answered 2xx so Graph doesn't retry it.
• lifecycleNotificationUrl is required for Teams subscriptions over an hour.

Found and fixed (bd78cbe). The README suggested --lifecycle-url https://your-endpoint/lifecycle, but the listener answered /lifecycle with 404. Graph validates the lifecycle URL as well as the notification URL when a subscription is created (Learn: lifecycle events), so following the README would have failed subscribe create. /lifecycle is now served like / and /webhook, with a unit test and a black-box test. The new unit test fails without the route. I updated the README, man page (wrapped for mandoc -Tlint), CLAUDE.md and CHANGELOG to match.

Rebased onto main (after #124, #125, #128 and #129), merging the CHANGELOG sections.

Test flake, not reproduced. client_state_filters_forged_notifications failed 3 times locally, only under heavy concurrent cargo builds, with ENOTCONN on the first write right after a successful connect(). About 650 further runs of the listen test binary (up to 4 in parallel with CPU burners) and 300 instant-POST startups did not reproduce it, and CI has never hit it. Rather than add a retry that could hide a real problem, 770b375 makes that helper's panic name the port and include the listener's stderr, so a recurrence will show what the listener was doing.

fmt, clippy -D warnings, all tests, mandoc and CI on all three OSes are green.