claimNext method

  1. @override
Future<RegenerationJob?> claimNext({
  1. DateTime? now,
  2. Duration lease = const Duration(minutes: 2),
})
override

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;
});