fisher 1.0.0

Webhooks catcher written in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

// Copyright (C) 2017 Pietro Albini
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <http://www.gnu.org/licenses/>.

//! Traits used by Fisher.

use std::hash::Hash;
use std::sync::Arc;
use std::fmt::Debug;

use super::prelude::*;
use super::structs::HealthDetails;


/// This trait represents a script that can be run by Fisher.
pub trait ScriptTrait {
    /// The type of the ID of the script. Must be hashable.
    type Id: Debug + Hash + PartialEq + Eq + Send + Copy + Clone;

    /// This method returns the unique ID of this script. The ID must be
    /// the same between calls to the same script.
    fn id(&self) -> Self::Id;

    /// This method returns if multiple instances of the script can be safely
    /// run in parallel.
    fn can_be_parallel(&self) -> bool;
}


/// This trait represents a repository of scripts.
pub trait ScriptsRepositoryTrait: Send + Sync {
    /// The type of the scripts. Must implement
    /// [`ScriptTrait`](trait.ScriptTrait.html).
    type Script: ScriptTrait + Send + Sync;

    /// The type of the jobs. Must implement [`JobTrait`](trait.JobTrait.html).
    type Job: JobTrait<Self::Script> + Debug + Send + Sync + Clone;

    /// The iterator returned by the `iter` method.
    type ScriptsIter: Iterator<Item = Arc<Self::Script>>;

    /// The iterator returned by the `jobs_after_output` method
    type JobsIter: Iterator<Item = Self::Job>;

    /// Get a script by its ID.
    fn id_exists(&self, id: &<Self::Script as ScriptTrait>::Id) -> bool;

    /// Get an iterator over all the scripts.
    fn iter(&self) -> Self::ScriptsIter;

    /// Return all the jobs generated as a conseguence of the result of another
    /// job.
    ///
    /// In Fisher, this is used to spawn status hooks when another job
    /// completes, but it can also return nothing.
    fn jobs_after_output(
        &self,
        output: <Self::Job as JobTrait<Self::Script>>::Output,
    ) -> Option<Self::JobsIter>;
}


/// This trait represents a Job that can be processed by Fisher.
pub trait JobTrait<S: ScriptTrait> {
    /// The context that will be provided to the job.
    type Context: Debug + Send + Sync;

    /// The output that will be returned by the job.
    type Output: Clone + Send + Sync;

    /// Execute the job and return the output of it.
    fn execute(&self, ctx: &Self::Context) -> Result<Self::Output>;

    /// Get the ID of the underlying script.
    fn script_id(&self) -> S::Id;

    /// Get the name of the underlying script.
    fn script_name(&self) -> &str;
}


/// This trait represents the API of the processor
pub trait ProcessorApiTrait<S: ScriptsRepositoryTrait>: Send {
    /// Queue a new job into the processor.
    fn queue(&self, job: S::Job, priority: isize) -> Result<()>;

    /// Get some insights about the health of the processor.
    fn health_details(&self) -> Result<HealthDetails>;

    /// Execute periodic cleanup tasks on the processor.
    fn cleanup(&self) -> Result<()>;

    /// Lock the processor, preventing new jobs to be run.
    fn lock(&self) -> Result<()>;

    /// Unlock the processor, allowing new jobs to be run.
    fn unlock(&self) -> Result<()>;
}