Several teams embed your Go package in long-lived daemons — how do you decide whether it may start goroutines itself?

## Why this is a decision and not a preference A package embedded in other teams' long-lived processes is not just code they call; it is code that runs inside their lifecycle. Every goroutine it starts must fit into their startup order, their drain, their shutdown deadline, their leak checks and their on-call runbook. They cannot opt out of it, and they usually cannot see it — it does not appear at any call site. That asymmetry is what makes it an ownership call. You get the convenience; they get the failure modes. A senior engineer can pick the right shape for one API. This question is about setting the policy for a package with several consumers you do not control, and being able to defend it when one of them wants the other answer. ## The default: a blocking core Export the work as a call that runs on the caller's goroutine and returns when it is done or cancelled. Consequences worth stating out loud: - Concurrency appears where the embedder wrote it, so their reviewers see it. - Their shutdown sequence already knows how to wait for something they started. - Errors return on the normal path, so they are handled in their idiom, not logged in yours. - Their leak checks stay meaningful, because nothing of yours survives a call. - How much runs at once is theirs to bound, which matters because they know their machine and you do not. If a consumer wants it in the background, that is one keyword in their code. ## When starting one is justified Some abstractions cannot exist without background work. Multiplexing a single handle among many subscribers. Refreshing a credential before it expires. Coalescing writes on a timer. Draining a kernel-level event source and fanning it out. In those cases the goroutine is the product: a purely synchronous version would just push the same goroutine into every consumer, written five slightly different ways. The test I apply: **could a competent caller implement this concurrency themselves from the synchronous API without losing a property?** If yes, do not start it. If no — because the concurrency is bound to a resource only the package holds — start it, and pay for it in the contract. ## What starting one commits you to 1. **Nothing in the constructor.** Construction allocates and validates. A separate, explicitly named call starts the work, so the call site shows where a lifetime began. 2. **One way to stop, and stopping means stopped.** The stop's return is the guarantee that the goroutine has exited and released its handles. "Signals the watcher to stop" is not something an embedder can order a shutdown around. 3. **A bounded, documented count.** "One goroutine per watcher" is a promise. "One per subscription, plus one per reconnect" is a leak that scales with their traffic and appears nowhere in the signature. 4. **Errors go somewhere the caller owns.** A callback they supply, a method they can poll, or a channel with a written contract. Never a log line in your chosen format — you would be picking their observability stack for them. 5. **A panic in your goroutine must not take their process down for a reason they cannot see.** Decide and document what happens, because they cannot recover in a goroutine they did not start. 6. **It is now API.** Adding a goroutine in a later version can break an embedder's leak test and their shutdown ordering, even though no exported signature changed. Removing one can change whether callbacks arrive concurrently. Both are behavioural compatibility problems, and both need a release note that reads like an API change. ## Serving the consumer who wants the convenience When a large consumer asks for the background form, the answer is rarely "no" and should never be "I will change the default". Offer both, with the safe one as the default and the convenient one obviously named at the call site — a blocking `Run(ctx) error` alongside something whose name says it starts something and hands back a stop. Two consequences: a reviewer in their repo can see which was chosen, and you keep exactly one implementation, with the convenience form as a thin wrapper you can reason about. ## Holding the line, and knowing when not to Expect pushback of the form "every consumer writes the same six lines". Sometimes that is a genuine signal that the concurrency belongs in the package, and the six lines are evidence to take seriously — if all five consumers wrote the same wrapper, the abstraction is missing. But check first whether they wrote the *same* six lines or five different ones; divergence usually means the right bounding differs per consumer, which is precisely the decision you must not make for them. The cost of getting this wrong is asymmetric, and that asymmetry is the argument. Too synchronous, and consumers write a little boilerplate you can later absorb. Too concurrent, and you have shipped a lifetime into several production processes that nobody can end without forking you.