/ 
App-karr-0.500
/ App::karr::Role::ClaimTimeout

NAME

App::karr::Role::ClaimTimeout - Shared claim timeout logic

VERSION

version 0.500

DESCRIPTION

Shared helper role for commands that need to interpret claim_timeout values and determine whether an existing claim should still block other agents.

check_claim is the one claim-ownership rule in karr. Every command that mutates an existing task has to apply it, and has to apply it against the same revision of the task it then writes -- see "update_task_guarded" in App::karr::Role::TaskMutation.

claim_timeout_secs

my $secs = $self->claim_timeout_secs;

In a command class that composes this role, returns the board's configured claim_timeout in seconds, parsed with the full Go time.ParseDuration grammar kanban-md writes (e.g. 1h30m), not just ^\d+[hms]$. Falls back to one hour (3600) when the board has no claim_timeout set or the value does not parse -- except an explicit 0s, which is honoured verbatim and means "claims never expire" (see karr unlock). This is the timeout "check_claim" applies; App::karr::Cmd::Pick's lock timeout is a separate, shorter fallback and does not go through this method.

check_claim

$self->check_claim( $task, $self->claim );   # $self->claim may be undef

In a command class that composes this role, decides whether $task's existing claim blocks the caller and either returns true or dies with "Task N is claimed by X\n". Four cases, checked in order:

  • the task is not claimed at all -- always allowed;

  • $claimant is defined, non-empty, and matches $task->claimed_by exactly -- the current claimant may always proceed;

  • the claim is older than "claim_timeout_secs" -- an expired claim no longer blocks anyone, but is not cleared as a side effect of asking (that stays kanban-md's behaviour, not karr's -- see the comment above this method for why);

  • otherwise -- the task belongs to someone still working on it, and the call dies rather than silently taking the claim over.

Call it against the same task revision the caller then writes -- see "update_task_guarded" in App::karr::Role::TaskMutation -- since a check made against a stale read can pass or fail against bytes that are no longer there.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/karr/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.