system-service 0.2.2

Framework to handle logging, signals, etc. so you can focus on business logic
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
110
111
112
113

// Copyright 2018 OneSignal, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// 	http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! A framework for writing system services
//!
//! # About
//!
//! Every application which runs as a service should implement things like
//! logging, signal handling, graceful shutdown, CLI option parsing, and
//! configuration file parsing. This package provides a semi-opinionated
//! framework for doing so.
//!
//! # Usage
//!
//! There are several traits exported here including [`Application`], [`Config`],
//! [`Options`], and [`LogOptions`]. The two options traits should be implemented
//! for your CLI option loadind, [`Config`] for your config file loading, and
//! [`Application`] for your application logic.
//!
//! The primary run method is [`Application::run_once`] which is called over and
//! over again in a loop. It is provided a [`Context`] type which gives the
//! application control of when it checks for signals. Any received signals are
//! passed to [`Application::received_signal`] for handling.
//!
//! Once [`Application::run_once`] returns [`Stopping::Yes`], the main loop
//! terminates and invokes [`Application::shutdown`] before exitting.
//!
//! [`Application`]: trait.Application.html
//! [`Application::run_once`]: trait.Application.html#tymethod.run_once
//! [`Application::received_signal`]: trait.Application.html#tymethod.received_signal
//! [`Application::shutdown`]: trait.Application.html#tymethod.shutdown
//! [`Stopping::Yes`]: enum.Stopping.html#variant.Yes
//! [`Config`]: trait.Config.html
//! [`Options`]: trait.Options.html
//! [`LogOptions`]: trait.LogOptions.html
//! [`Context`]: struct.Context.html

#[macro_use] extern crate chan;
#[macro_use] extern crate log;

extern crate chan_signal;
extern crate env_logger;

/// Print a message to stderr and exit(1)
#[macro_export]
macro_rules! die {
    ($($arg:tt)*) => {{
        eprintln!($($arg)*);
        ::std::process::exit(1);
    }}
}

mod application; // general app stuff
mod logging;

pub use application::{
    Application,
    Stopping,
    Config,
    Options,
    Context
};

pub use logging::LogOptions;

/// Run an Application
///
/// This should be called in your `fn main()` with something like the following.
///
/// ```rust
/// fn main() {
///     if let Err(err) = run::<MyApplication>() {
///         die!("Application encountered error: {}", err);
///     }
/// }
/// ```
///
/// CLI option loading, config loading, signal handling, and etc. are all
/// initialized automatically on the Application's behalf.
pub fn run<T>() -> Result<(), T::Err>
    where T: Application
{
    let signal = chan_signal::notify(T::signals());
    let context = Context { signal };

    let opts = T::Options::load();

    let _ = logging::init::<T::Options>(&opts);
    let config = Config::load(&opts);

    let mut app = T::new(opts, config)?;

    loop {
        if let Stopping::Yes = app.run_once(&context)? {
            break;
        }
    }

    app.shutdown()?;

    Ok(())
}