docs: say where async waits with no worker - #52
Merged
Conversation
solid-objects-js#22 reported that its README never said a process claims nothing until the roles start. An external prober built a two-process harness from that page and read the unclaimed messages as stranded. The gem states the rule in Worker requirements, but the async section, which is where a reader actually is when the question occurs to them, only said execution is left to the worker fleet. The async section now says the generator and the migrations start no role, so an application that serves web requests alone leaves the message ready until solid_objects start runs the roles, and points at the feature-by-role table. The runtime section of the operations guide says the same, with the boundary that makes it make sense: a direct call or an explicit sync needs no running role. test/integration/background_pickup_test.rb keeps it honest. The message reads ready and the actor state stays empty until a worker runs, then reads completed. Running a worker before the first assertion turns it red, so the assertion detects pickup rather than asserting a constant. The enqueue does create the instance row, because it allocates the mailbox sequence, so the test asserts on empty state rather than on a missing row.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The Ruby counterpart of
solid-objects-js#27,
which closes
solid-objects-js#22.
Why
The JS issue came from an external prober who built a two-process harness from
the README, watched ready messages sit unclaimed for 30 seconds, and concluded
messages were stranded. Nothing was wrong with the runtime. The page never said
that installing starts no role.
The gem is in better shape than the Node package was.
## Worker requirementsalready carries the feature-by-role table and the exact sentence a worried
reader needs:
What was missing is the pointer at the point of use. A reader who jumps to
### asyncfrom the table of contents reads only that execution is "left tothe worker fleet," which does not tell them a fleet has to exist, or what
happens meanwhile.
What changed
README, in the
asyncsection:docs/operations.md, in the runtime section: the same claim, plus the
boundary that makes it make sense. A direct call or an explicit
syncneeds norunning role, because the caller's own path executes it.
Keeping the sentence honest
test/integration/background_pickup_test.rbpins the documented behavior:A test that only ever sees
readyproves nothing, so I checked that the firstassertion detects pickup. Running a worker before it turns the test red:
One detail worth recording, because it surprised me while writing the test: the
enqueue does create the instance row, since it locks the instance to allocate
the mailbox sequence. So "nothing ran yet" shows up as empty state, not as a
missing row. The first draft asserted a missing row and failed:
Effects
docs/roadmap.mdis untouched, per AGENTS.md: this edits prose and adds a testrather than moving what the project claims about itself.
Validation
bundle exec rake(test, standard, rubocop, rbs, steep, security): pass.