praxis_protocol/protocol.rs
1// SPDX-License-Identifier: Apache-2.0
2// Copyright (c) 2024 Praxis Contributors
3
4//! The [`Protocol`] trait implemented by each listener protocol adapter.
5//!
6//! An implementor binds its listeners and registers the matching Pingora
7//! services onto the shared [`PingoraServerRuntime`]. The server crate calls
8//! [`Protocol::register`] once per configured protocol at startup; the HTTP and
9//! TCP adapters live in [`crate::http`] and [`crate::tcp`].
10//!
11//! [`PingoraServerRuntime`]: praxis_core::PingoraServerRuntime
12
13use praxis_core::{PingoraServerRuntime, ProxyError, config::Config};
14use tokio::sync::watch;
15
16use crate::ListenerPipelines;
17
18/// A protocol implementation that registers services onto a shared server runtime.
19pub trait Protocol: Send {
20 /// Register this protocol's services. Does not block.
21 ///
22 /// Returns any TLS certificate watcher shutdown senders. The caller keeps
23 /// these alive to retain the ability to stop a watcher early via
24 /// `send(true)`; the watcher tasks otherwise run for the process lifetime
25 /// (dropping the senders does not stop them).
26 ///
27 /// # Errors
28 ///
29 /// Returns [`ProxyError`] if listener binding or setup fails.
30 ///
31 /// [`ProxyError`]: praxis_core::ProxyError
32 fn register(
33 self: Box<Self>,
34 server: &mut PingoraServerRuntime,
35 config: &Config,
36 pipelines: &ListenerPipelines,
37 ) -> Result<Vec<watch::Sender<bool>>, ProxyError>;
38}