Skip to content

Says which use options the attempt cap ignores - #142

Merged
johnnyt merged 1 commit into
mainfrom
sob-tfq-attempt-cap-options-caveats
Sep 29, 2026
Merged

johnnyt merged 1 commit into
mainfrom
sob-tfq-attempt-cap-options-caveats

Conversation

@johnnyt

@johnnyt johnnyt commented Sep 29, 2026

Copy link
Copy Markdown
Member

Summary

The README's "Capping a handler's attempts" section said any :max_attempts value other than a positive integer fails the handler's compile, and the StatifierOban.Invoke.Handler moduledoc sentence just before its literal-options paragraph said the same. Both now match that paragraph:

  • README: the options must be a literal keyword list in the use; a keyword list reaching it through a module attribute, a variable or a function call is ignored whole, as is any argument that is not a keyword list; the one key read is :max_attempts and any other key is ignored; max_attempts: nil declares no cap; none of these is an error.
  • Moduledoc: the sentence now says any other value fails the compile except in the cases the next paragraph lists, none of which is an error.

No other README section changes. Docs only; no behaviour changes, so no changelog fragment (changelog.d/README.md excludes documentation).

Review (in-turn, gate tier)

Each claim was checked against lib/statifier_oban/invoke/handler.ex by anchor: __using__/1 reads :max_attempts only when Keyword.keyword?(opts) holds on the use argument as written, so an attribute, a variable, a call or a non-list argument yields no cap, and Keyword.get/2 reads only that key; __max_attempts__!/2 answers nil for nil and raises ArgumentError for any value that is not a positive integer; put_max_attempts/2 adds nothing to the job when the handler's cap is nil. The misspelled-key and non-literal cases are pinned by the tests "an unknown key in the use options compiles clean and stores no cap" and "use options that are not a literal keyword list compile and store no cap" in test/statifier_oban/invoke/handler_test.exs; the bad-value raise by "a cap that is not a positive integer fails the handler's compile". No test compiles a handler with an explicit max_attempts: nil; that gap is noted for follow-up, not changed here.

Gate

The edit is in lib/, a build path, so the full mix quality ran green on the rebased head (313 of 313 tests).

Refs: sob-tfq

The README's "Capping a handler's attempts" section said any
:max_attempts value other than a positive integer fails the handler's
compile, and the Invoke.Handler moduledoc sentence just before its
literal-options paragraph said the same. Neither matched the code:
__using__/1 reads the options only when the use argument is a literal
keyword list and reads only :max_attempts from it, and
__max_attempts__!/2 answers nil for nil. The README now says the
options must be a literal keyword list in the use, that a list held in
an attribute, a variable or a call is ignored whole, that any other key
is ignored, and that max_attempts: nil declares no cap. The moduledoc
sentence now defers to the paragraph that follows it. Docs only; no
behaviour changes and no changelog fragment (documentation is
excluded by changelog.d/README.md).

Refs: sob-tfq
@johnnyt
johnnyt merged commit 5986711 into main Sep 29, 2026
1 check passed
@johnnyt
johnnyt deleted the sob-tfq-attempt-cap-options-caveats branch September 29, 2026 04:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant