claimNext method
Implementation
@override
Future<RegenerationJob?> claimNext({
DateTime? now,
Duration lease = const Duration(minutes: 2),
}) async => _locked(() async {
if (lease <= Duration.zero) {
throw ArgumentError('lease must be positive.');
}
final time = (now ?? DateTime.now()).toUtc();
final state = await _syncState();
// 1. Recover expired leases from processing jobs
final expiredJobIds = <String>[];
for (final entry in state.processing.entries) {
final leaseUntil = entry.value;
if (!leaseUntil.isAfter(time)) {
expiredJobIds.add(entry.key);
}
}
for (final id in expiredJobIds) {
state.processing.remove(id);
final job = await _tryRead(id);
if (job != null && job.status == RegenerationJobStatus.processing) {
final recovered = job.attempts >= job.maxAttempts
? job.copyWith(
status: RegenerationJobStatus.failed,
clearLease: true,
errorCode: 'worker_lease_expired',
)
: job.copyWith(
status: RegenerationJobStatus.queued,
availableAt: time,
clearLease: true,
errorCode: 'worker_lease_expired',
);
await _save(recovered);
if (recovered.status == RegenerationJobStatus.queued) {
state.pending.add(id);
}
await _appendJournal({
'seq': ++state.lastSeq,
'op': 'fail',
'id': id,
'status': recovered.status.name,
'token': job.leaseToken,
});
}
}
// 2. Enforce concurrency limits
if (state.processing.length >= maxProcessingJobs) {
return null;
}
// 3. Track active processing paths for mutual exclusion
final workingPaths = <String>{};
for (final id in state.processing.keys) {
final job = await _tryRead(id);
if (job != null &&
job.status == RegenerationJobStatus.processing &&
job.leaseUntil != null &&
job.leaseUntil!.isAfter(time)) {
workingPaths.add('${job.siteId}|${job.tenantId}|${job.path}');
}
}
// 4. Find the first eligible pending job
String? claimedId;
RegenerationJob? readyJob;
for (final id in state.pending) {
final job = await _tryRead(id);
if (job == null || job.status != RegenerationJobStatus.queued) {
continue;
}
if (!job.availableAt.isAfter(time) &&
!workingPaths.contains('${job.siteId}|${job.tenantId}|${job.path}')) {
claimedId = id;
readyJob = job;
break;
}
}
if (claimedId == null || readyJob == null) {
return null;
}
state.currentEpoch++;
final leaseUntil = time.add(lease);
final token = 'epoch_${state.currentEpoch}_${readyJob.id}_${_queueNonce()}';
final claimedJob = readyJob.copyWith(
status: RegenerationJobStatus.processing,
attempts: readyJob.attempts + 1,
leaseUntil: leaseUntil,
leaseToken: token,
fencingEpoch: state.currentEpoch,
clearLease: false,
);
await _save(claimedJob);
state.pending.remove(claimedId);
state.processing[claimedId] = leaseUntil;
await _appendJournal({
'seq': ++state.lastSeq,
'op': 'claim',
'id': claimedId,
'leaseUntil': leaseUntil.toIso8601String(),
'token': token,
'epoch': state.currentEpoch,
});
if (state.lastSeq % 1000 == 0) {
await _checkpointInternal();
}
return claimedJob;
});