feat: KafkaProxy threading and lifecycle contract

[SamBarker]

Summary

Define the threading and lifecycle contract for KafkaProxy: single-use, idempotent startup()/shutdown(), future-returning startup() API, deprecation of block().

This is a prerequisite for the virtual cluster lifecycle work in 016 — defining the outer proxy contract first so that inner components can make informed concurrency decisions.

Key decisions

• KafkaProxy is single-use: NEW → STARTING → STARTED → STOPPING → STOPPED
• startup() returns a CompletableFuture<Void> that completes when the proxy stops — replaces block()
• Both startup() and shutdown() are idempotent — callers do not need to coordinate
• shutdown() may be called from any thread (JVM shutdown hook)
• The only error is startup() after STOPPING/STOPPED (not restartable)
• No FAILED state at proxy level — failure propagates via exception, proxy is not reconfigurable

Test plan

• Review proposal for completeness and consistency
• Confirm alignment with virtual cluster lifecycle proposal (016)

🤖 Generated with Claude Code

[tombentley]

Thanks @SamBarker

[tombentley]

Thanks Sam! I think the proposal is becoming clearer to me now, and it makes sense. I've made a few suggestions for how it's being explained.

[tombentley]

I think this section would be clearer if you at least started by laying out the signatures of the relevant lifecycle methods of KafkaProxy: startup(), shutdown() and block(). I think it might even just be simpler to show the javadoc for the contract you're proposing.

[k-wall]

as block is an internal API, we could just kill it.

[k-wall]

LGTM - thanks for formalizing this.

[k-wall]

Hi! We've updated the proposal numbering system to use PR numbers as proposal identifiers.

Action required: Please rebase your PR on main.

Once you rebase, you'll need to rename your proposal file and update the title:

git mv proposals/019-kafkaproxy-threading-and-lifecycle.md proposals/098-threading-and-lifecycle.md
# Update title: remove any old number prefix and add PR number
sed -i.bak '0,/^# /{s/^# \([0-9]\{3\}\|xxx\|nnn\|000\) - /# 98 - /; t; s/^# /# 98 - /}' proposals/098-threading-and-lifecycle.md && rm proposals/098-threading-and-lifecycle.md.bak
git add proposals/098-threading-and-lifecycle.md
git commit -m "Rename proposal to use PR number"
git push

The GitHub workflow will automatically check your proposal file naming after you push and update this PR description if any corrections are still needed.

See proposals/README.md for the updated workflow.

[k-wall]

Correction: The previous notification had an incorrect filename. Here are the correct commands:

git mv proposals/019-kafkaproxy-threading-and-lifecycle.md proposals/098-kafkaproxy-threading-and-lifecycle.md
# Update title: remove any old number prefix and add PR number
sed -i.bak '0,/^# /{s/^# \([0-9]\{3\}\|xxx\|nnn\|000\) - /# 98 - /; t; s/^# /# 98 - /}' proposals/098-kafkaproxy-threading-and-lifecycle.md && rm proposals/098-kafkaproxy-threading-and-lifecycle.md.bak
git add proposals/098-kafkaproxy-threading-and-lifecycle.md
git commit -m "Rename proposal to use PR number"
git push

Sorry for the confusion!