ora_backend/
lib.rs

1//! Common storage and timer backend interfaces for the Ora server.
2
3use std::future::Future;
4
5use futures::Stream;
6
7use crate::{
8    common::NextPageToken,
9    executions::{
10        FailedExecution, InProgressExecution, ReadyExecution, StartedExecution, SucceededExecution,
11    },
12    jobs::{CancelledJob, JobDetails, JobFilters, JobId, JobOrderBy, JobType, NewJob},
13    schedules::{
14        PendingSchedule, ScheduleDefinition, ScheduleDetails, ScheduleFilters, ScheduleId,
15        ScheduleOrderBy, StoppedSchedule,
16    },
17};
18
19pub mod common;
20pub mod executions;
21pub mod executors;
22pub mod jobs;
23pub mod schedules;
24
25#[cfg(feature = "test")]
26pub mod test;
27
28/// Backend implementation for the Ora server.
29///
30/// A backend is responsible for all storage operations as well
31/// as timing of executions.
32pub trait Backend: Send + Sync + 'static {
33    /// The error type for backend operations.
34    type Error: core::error::Error + Send + Sync + 'static;
35
36    /// Add or update job types.
37    fn add_job_types(
38        &self,
39        job_types: &[JobType],
40    ) -> impl Future<Output = Result<(), Self::Error>> + Send;
41    /// List all job types.
42    fn list_job_types(&self) -> impl Future<Output = Result<Vec<JobType>, Self::Error>> + Send;
43
44    /// Add new jobs and return their IDs in the same order.
45    ///
46    /// For each new job an execution must also be created.
47    ///
48    /// If `if_not_exists` is provided and any jobs exist
49    /// matching the given filters, no new jobs must be added
50    /// and an empty list must be returned.
51    fn add_jobs(
52        &self,
53        jobs: &[NewJob],
54        if_not_exists: Option<JobFilters>,
55    ) -> impl Future<Output = Result<Vec<JobId>, Self::Error>> + Send;
56
57    /// List jobs matching the given filters.
58    fn list_jobs(
59        &self,
60        filters: JobFilters,
61        order_by: Option<JobOrderBy>,
62        page_size: u32,
63        page_token: Option<NextPageToken>,
64    ) -> impl Future<Output = Result<(Vec<JobDetails>, Option<NextPageToken>), Self::Error>> + Send;
65
66    /// Count the jobs matching the given filters.
67    fn count_jobs(
68        &self,
69        filters: JobFilters,
70    ) -> impl Future<Output = Result<u64, Self::Error>> + Send;
71
72    /// Cancel the jobs matching the given filters, returning
73    /// the cancelled jobs.
74    fn cancel_jobs(
75        &self,
76        filters: JobFilters,
77    ) -> impl Future<Output = Result<Vec<CancelledJob>, Self::Error>> + Send;
78
79    /// Add new schedules and return their IDs in the same order.
80    ///
81    /// If `if_not_exists` is provided and any schedules exist
82    /// matching the given filters, no new schedules must be added
83    /// and an empty list must be returned.
84    fn add_schedules(
85        &self,
86        schedules: &[ScheduleDefinition],
87        if_not_exists: Option<ScheduleFilters>,
88    ) -> impl Future<Output = Result<Vec<ScheduleId>, Self::Error>> + Send;
89
90    /// List schedules matching the given filters.
91    fn list_schedules(
92        &self,
93        filters: ScheduleFilters,
94        order_by: Option<ScheduleOrderBy>,
95        page_size: u32,
96        page_token: Option<NextPageToken>,
97    ) -> impl Future<Output = Result<(Vec<ScheduleDetails>, Option<NextPageToken>), Self::Error>> + Send;
98
99    /// Count the schedules matching the given filters.
100    fn count_schedules(
101        &self,
102        filters: ScheduleFilters,
103    ) -> impl Future<Output = Result<u64, Self::Error>> + Send;
104
105    /// Stop the schedules matching the given filters, returning
106    /// the IDs of the stopped schedules.
107    fn stop_schedules(
108        &self,
109        filters: ScheduleFilters,
110    ) -> impl Future<Output = Result<Vec<StoppedSchedule>, Self::Error>> + Send;
111
112    /// Return ready executions.
113    ///
114    /// The executions must be ordered by their ID.
115    ///
116    /// The batch size of ready executions returned by the stream
117    /// is backend-dependent.
118    fn ready_executions(
119        &self,
120    ) -> impl Stream<Item = Result<Vec<ReadyExecution>, Self::Error>> + Send;
121
122    /// Wait for executions to be ready.
123    fn wait_for_ready_executions(&self) -> impl Future<Output = Result<(), Self::Error>> + Send;
124
125    /// Return a stream of in-progress executions.
126    ///
127    /// These are executions that have been started by executors
128    /// but have not yet completed, failed, or been cancelled.
129    fn in_progress_executions(
130        &self,
131    ) -> impl Stream<Item = Result<Vec<InProgressExecution>, Self::Error>> + Send;
132
133    /// The given executions have started.
134    ///
135    /// The backend must update the execution records accordingly.
136    fn executions_started(
137        &self,
138        executions: &[StartedExecution],
139    ) -> impl Future<Output = Result<(), Self::Error>> + Send;
140
141    /// The given executions have successfully completed.
142    fn executions_succeeded(
143        &self,
144        executions: &[SucceededExecution],
145    ) -> impl Future<Output = Result<(), Self::Error>> + Send;
146
147    /// The given executions have failed.
148    fn executions_failed(
149        &self,
150        executions: &[FailedExecution],
151    ) -> impl Future<Output = Result<(), Self::Error>> + Send;
152
153    /// The given executions have failed but need to be retried.
154    ///
155    /// For each job, a new execution must be created.
156    fn executions_retried(
157        &self,
158        executions: &[FailedExecution],
159    ) -> impl Future<Output = Result<(), Self::Error>> + Send;
160
161    /// Return a stream of active schedules that do not have
162    /// an active job.
163    fn pending_schedules(
164        &self,
165    ) -> impl Stream<Item = Result<Vec<PendingSchedule>, Self::Error>> + Send;
166
167    /// Wait for pending schedules to be available.
168    fn wait_for_pending_schedules(&self) -> impl Future<Output = Result<(), Self::Error>> + Send;
169
170    /// Delete historical data for inactive jobs and schedules.
171    ///
172    /// The following should be deleted:
173    /// - Jobs with executions that finished before the given time.
174    /// - Schedules that were stopped before the given time.
175    /// - Delete job types that are not referenced by any jobs.
176    fn delete_history(
177        &self,
178        before: std::time::SystemTime,
179    ) -> impl Future<Output = Result<(), Self::Error>> + Send;
180}
ora_backend/lib.rs

ora_backend/
lib.rs
