4.4.4 Persistent Workers for Rule Authors

Persistent workers are worth adding only when the rule and the underlying tool can uphold a stronger contract than a normal one-shot action. Bazel can keep a worker process alive and send it many requests, but the rule author must define what stays stable at process startup, what varies per action, how Bazel talks to the process, and how correctness is preserved when state survives between requests.¹ This builds on the execution-strategy vocabulary from 2.5 Execution Strategies. This article focuses on the rule-author surface, while pool sizing and performance operations continue in 6.4 Execution Modes and Persistent Workers.

Start with the Tool, Not the Flag

A worker is either the tool itself or a wrapper around the tool. It must accept --persistent_worker, then read WorkRequest messages from stdin and write WorkResponse messages to stdout. When the flag is absent, it should still be able to run as a normal one-shot tool.² That fallback matters because Bazel may invoke the same executable with and without worker mode in one build, depending on strategy selection and action support.³

Good worker candidates have repeated actions with high startup cost or useful cross-action caches: compilers, transpilers, code generators, and analysis tools. The official docs call out startup overhead, JIT warmup, and cached ASTs as the common wins.⁴ In practical terms, workers help when the compiler is architected to reset and reuse state safely. They are not a magic adapter for arbitrary command-line tools.⁵

The strongest design question is therefore: can the tool behave as if every request were isolated? If the tool leaves global state behind, uses process-wide temp files, or writes diagnostics to the wrong stream, worker mode can turn a harmless one-shot bug into a sequence-dependent build failure.⁶

The Rule-Side Contract

The Starlark rule must expose a stable executable, usually through a private executable attr in the execution configuration, so the worker runs on the execution platform rather than the target platform.⁷ It must also register actions with a stable mnemonic, because users route worker strategy by mnemonic:

_my_rule = rule(
    implementation = _impl,
    attrs = {
        "_worker": attr.label(
            default = Label("//tools/my_compiler:worker"),
            executable = True,
            cfg = "exec",
        ),
    },
)

The action must declare worker support through execution_requirements. supports-workers opts the action into the worker strategy, while requires-worker-protocol selects JSON or protobuf. Protobuf is the default when the protocol key is omitted.⁸ That protocol selection is part of the action's execution contract: when remote execution is involved, Bazel forwards it as the persistentWorkerProtocol platform property so the remote side sees the same protocol expectation.⁹

args_file = ctx.actions.declare_file(ctx.label.name + ".worker.args")
ctx.actions.write(
    output = args_file,
    content = "\n".join(per_request_args),
)

ctx.actions.run(
    executable = ctx.executable._worker,
    inputs = depset(direct = [args_file], transitive = [src_inputs]),
    outputs = [out],
    arguments = [
        "--max_mem=4G",          # startup argument
        "@%s" % args_file.path,  # per-request arguments
    ],
    mnemonic = "MyCompiler",
    execution_requirements = {
        "supports-workers": "1",
        "requires-worker-protocol": "proto",
    },
)

The arguments list has two roles. Everything before the final @flagfile is a startup argument for the worker process. The flagfile content becomes the per-request argument list in each WorkRequest.¹⁰ Keep startup arguments low-cardinality: Bazel includes the mnemonic and startup flags in the worker key, so letting every target choose different startup options can multiply live worker processes and memory use.¹¹

The Protocol Is Part of the API

A WorkRequest carries request arguments, input path/digest pairs, and a request id. A WorkResponse carries the same request id, an exit code, and an output message.¹² For singleplex workers, the request id is 0. Multiplex workers use nonzero ids to match concurrent responses to requests.¹³

stdout is reserved for protocol messages. If the worker or a wrapped compiler writes ordinary diagnostics there, Bazel can no longer reliably parse responses. Capture tool output and put user-facing text in the WorkResponse.output field. Use the worker process stderr only for worker logs, knowing that those logs are attached to the worker process rather than one specific action.¹⁴

JSON and protobuf carry the same logical fields, but JSON uses camelCase names such as requestId. Protobuf uses snake_case fields such as request_id. JSON workers must tolerate unknown fields and protobuf defaults.¹⁵ That detail sounds small until you maintain wrappers in multiple languages: even reading protobuf messages from an unbounded stdin stream requires library-level care around length-delimited messages.¹⁶

Correctness Before Warmth

Worker performance comes from keeping process state warm. Worker correctness comes from proving that warm state cannot change outputs for the wrong request. Bazel sends input digests in the request so the worker or wrapper can validate cached compiler state against the inputs Bazel knows about, but this is cooperative: it does not by itself prevent hidden in-memory state from leaking between requests.¹⁷

Use --worker_sandboxing while developing and testing a worker-backed rule. It gives each request a sandboxed input view, which catches many undeclared input problems, but it is still weaker than a fresh one-shot sandbox because the process can retain internal state.¹⁸ A real GHC worker port surfaced test failures when the compiler had host-side access it should not have had. The practical fix was to always test worker mode with sandboxing enabled.¹⁹

Cancellation is another correctness boundary. Workers can opt into cancellation with supports-worker-cancellation: 1 plus --experimental_worker_cancellation. Even when a request is cancelled, each non-cancel request must be answered exactly once, and after sending the response the worker must not touch files in its working directory because Bazel may clean them up.²⁰

Multiplex Workers Raise the Bar

Multiplex workers are a different promise, not just a faster checkbox. A multiplex worker lets one process handle several concurrent requests, which can reduce memory pressure and share one cache across requests for tools such as Java or Scala compilers.²¹ To opt in, the action declares supports-multiplex-workers. This takes precedence over supports-workers when both are present.²²

The worker implementation then has to become thread-safe. It must preserve request_id, write responses atomically so messages do not interleave, and handle user-visible output without mixing text from parallel requests.²³ If multiplex sandboxing is needed, the worker must read sandbox_dir from each WorkRequest, translate all input and output paths through that directory, and declare supports-multiplex-sandboxing on the action. Bazel still needs --experimental_worker_multiplex_sandboxing or a dynamic-execution path that requires multiplex sandboxing before that support is used.²⁴

Treat multiplexing as an extra capability after the singleplex contract is proven. A non-thread-safe worker with shared temp files, global compiler state, or output written straight to stderr is not ready for multiplex mode.²⁵

The runnable mini-ruleset connects both halves of the contract: the worker-backed action and its persistent worker adapter.