import '../../../core/api_gateway.dart'; import '../domain/saved_schedule.dart'; import '../domain/schedule_json.dart'; /// Client-side protocol failure. Server refusals and transport errors are not /// wrapped: [ApiGateway] already surfaces their exact text. class SchedulesRepositoryException implements Exception { const SchedulesRepositoryException(this.message); final String message; @override String toString() => message; } /// The saved-schedule commands of the current web client. /// /// These are run configurations, not pipeline definitions: this repository /// never submits, validates or publishes a workflow, and it never starts or /// polls a run. Timer execution belongs to the server. class SchedulesRepository { SchedulesRepository(this._gateway); final ApiGateway _gateway; /// Lists saved schedules, optionally for one pipeline. /// /// An explicit empty reply is a valid empty list. A reply without the /// `schedules` type is not: that is an older/unsupported server and must be /// reported rather than shown as "no schedules". Future> listSchedules({int? pipelineId}) async { final fields = {}; if (pipelineId != null) { if (!_isPositiveId(pipelineId)) { throw const SchedulesRepositoryException( 'A positive pipeline ID is required.', ); } fields['pipeline_id'] = pipelineId; } final reply = await _gateway.call('list_schedules', fields); final schedules = reply['schedules']; if (reply['type'] != 'schedules' || (schedules != null && schedules is! List)) { throw const SchedulesRepositoryException( 'The server returned no schedules response.', ); } if (schedules == null) return const []; return [ for (final item in schedules as List) if (item is Map) SavedSchedule(Map.from(item)) else throw const SchedulesRepositoryException( 'The server returned an invalid schedule record.', ), ]; } /// Creates or updates one saved schedule. /// /// Creation sends the web client's sentinel record (`id` 0, no revision) and /// may carry a stable request key so a lost reply is retried instead of /// creating a duplicate. Updating sends the record read from the server, /// whose `revision` is the compare-and-swap token; the key is omitted, as in /// the web client. A stale revision is refused by the server and propagated /// unchanged, never overwritten locally. Future saveSchedule( JsonMap schedule, { String? requestKey, }) async { if (requestKey != null && requestKey.length > 128) { throw const SchedulesRepositoryException( 'Schedule request keys must be strings of at most 128 characters.', ); } final fields = {'schedule': cloneJsonMap(schedule)}; if (requestKey != null && requestKey.isNotEmpty) { fields['request_key'] = requestKey; } final reply = await _gateway.call('save_schedule', fields); final saved = reply['schedule']; if (saved is! Map) { throw const SchedulesRepositoryException( 'The server returned no saved schedule.', ); } return SavedSchedule(Map.from(saved)); } /// Deletes exactly the revision the caller read. /// /// Both identity and revision are required before any request is sent; a /// confirmation for a different schedule is treated as a failed delete. Future deleteSchedule(int id, int revision) async { if (!_isPositiveId(id) || !_isPositiveId(revision)) { throw const SchedulesRepositoryException( 'An exact schedule ID and revision are required.', ); } final reply = await _gateway.call('delete_schedule', { 'schedule_id': id, 'expected_revision': revision, }); if (reply['type'] != 'schedule_deleted' || reply['schedule_id'] != id) { throw const SchedulesRepositoryException( 'The server did not confirm deletion of this schedule.', ); } } } /// JSON/JavaScript integers are safe up to 2^53-1; the web client checks /// `Number.isSafeInteger` before sending an identity. const _maxSafeInteger = 9007199254740991; bool _isPositiveId(int value) => value > 0 && value <= _maxSafeInteger;