Struct Server 

pub struct Server {
    pub configuration: Arc<ServerConf>,
    pub options: Option<Opt>,
    /* private fields */
}

The server object

This object represents an entire pingora server process which may have multiple independent services (see crate::services). The server object handles signals, reading configuration, zero downtime upgrade and error reporting.

Fields

configuration: Arc<ServerConf>

The parsed server configuration

options: Option<Opt>

The parser command line options

Implementations

impl Server

pub fn watch_execution_phase(&self) -> Receiver<ExecutionPhase>

Acquire a receiver for the server’s execution phase.

The receiver will produce values for each transition.

pub fn new_with_opt_and_conf( raw_opt: impl Into<Option<Opt>>, conf: ServerConf, ) -> Server

Create a new Server, using the Opt and ServerConf values provided

This method is intended for pingora frontends that are NOT using the built-in command line and configuration file parsing, and are instead using their own.

If a configuration file path is provided as part of opt, it will be ignored and a warning will be logged.

pub fn new(opt: impl Into<Option<Opt>>) -> Result<Server>

Create a new Server.

Only one Server needs to be created for a process. A Server can hold multiple independent services.

Command line options can either be passed by parsing the command line arguments via Opt::parse_args(), or be generated by other means.

pub fn add_service( &mut self, service: impl ServiceWithDependents + 'static, ) -> ServiceHandle

Add a service to this server.

Returns a ServiceHandle that can be used to declare dependencies.

Example

let db_id = server.add_service(database_service);
let api_id = server.add_service(api_service);

// Declare that API depends on database
api_id.add_dependency(&db_id);

pub fn add_boxed_service( &mut self, service_box: Box<dyn ServiceWithDependents>, ) -> ServiceHandle

Add a pre-boxed service to this server.

Returns a ServiceHandle that can be used to declare dependencies.

Example

let db_id = server.add_service(database_service);
let api_id = server.add_service(api_service);

// Declare that API depends on database
api_id.add_dependency(&db_id);

pub fn add_services( &mut self, services: Vec<Box<dyn ServiceWithDependents>>, ) -> Vec<ServiceHandle>

Similar to Self::add_service(), but take a list of services.

Returns a Vec<ServiceHandle> for all added services.

pub fn bootstrap(&mut self)

Prepare the server to start

When trying to zero downtime upgrade from an older version of the server which is already running, this function will try to get all its listening sockets in order to take them over.

pub fn bootstrap_as_a_service(&mut self) -> ServiceHandle

Create a service that will run to prepare the service to start

The created service will handle the zero-downtime upgrade from an older version of the server to this one. It will try to get all its listening sockets in order to take them over.

Other bootstrapping functionality like sentry initialization will also be handled, but as a service that will complete before any other service starts.

pub fn run_forever(self) -> !

Start the server using Self::run and default RunArgs.

This function will block forever until the server needs to quit. So this would be the last function to call for this object.

Note: this function may fork the process for daemonization, so any additional threads created before this function will be lost to any service logic once this function is called.

pub fn run(self, run_args: RunArgs)

Run the server until execution finished.

This function will run until the server has been instructed to shut down through a signal, and will then wait for all services to finish and runtimes to exit.

Note: if daemonization is enabled in the config, this function will never return. Instead it will either start the daemon process and exit, or panic if daemonization fails.