parsec_service/front/
listener.rs

1// Copyright 2019 Contributors to the Parsec project.
2// SPDX-License-Identifier: Apache-2.0
3//! Interface for service IPC front
4//!
5//! The [`Listen`](https://parallaxsecond.github.io/parsec-book/parsec_service/listeners.html)
6//! trait acts as an interface for the operations that must be supported by any implementation
7//! of the IPC mechanism used as a Parsec front.
8use derivative::Derivative;
9use std::time::Duration;
10
11/// This trait is created to allow the iterator returned by incoming to iterate over a trait object
12/// that implements both Read and Write.
13pub trait ReadWrite: std::io::Read + std::io::Write {}
14// Automatically implements ReadWrite for all types that implement Read and Write.
15impl<T: std::io::Read + std::io::Write> ReadWrite for T {}
16
17/// Specifies metadata associated with a connection, if any.
18#[derive(Copy, Clone, Debug)]
19pub enum ConnectionMetadata {
20    /// Unix peer credentials metadata for Unix domain sockets.
21    UnixPeerCredentials {
22        /// The effective UID of the connecting process.
23        uid: u32,
24        /// The effective GID of the connecting process.
25        gid: u32,
26        /// The optional PID of the connecting process. This is an Option<u32> because not all
27        /// platforms support retrieving PID via a domain socket.
28        pid: Option<i32>,
29    },
30    // NOTE: there is currently only _one_ variant of the ConnectionMetadata enum. When a second
31    //       variant is added, you will need to update some tests!
32    //       You should grep the tests for `TODO(new_metadata_variant)` and update them accordingly.
33}
34
35/// Represents a connection to a single client
36#[derive(Derivative)]
37#[derivative(Debug)]
38pub struct Connection {
39    /// Stream used for communication with the client
40    #[derivative(Debug = "ignore")]
41    pub stream: Box<dyn ReadWrite + Send>,
42    /// Metadata associated with the connection that might be useful elsewhere (i.e. authentication, etc)
43    pub metadata: Option<ConnectionMetadata>,
44}
45
46/// IPC front manager interface
47///
48/// Interface defining the functionality that any IPC front manager has to expose to Parsec for normal
49/// operation.
50pub trait Listen {
51    /// Set the timeout on read and write calls on any stream returned by this listener.
52    fn set_timeout(&mut self, duration: Duration);
53
54    /// Non-blocking call that gets the next client connection and returns a stream
55    /// (a Read and Write trait object). Requests are read from the stream and responses are written
56    /// to it. Streams returned by this method should have a timeout period as set by the
57    /// `set_timeout` method.
58    /// If no connections are present, return `None`.
59    /// If there are any errors in establishing the connection other than the missing
60    /// initialization, the implementation should log them and return `None`.
61    /// `Send` is needed because the stream is moved to a thread.
62    ///
63    /// # Panics
64    ///
65    /// If the listener has not been initialised before, with the `init` method.
66    fn accept(&self) -> Option<Connection>;
67}
parsec_service/front/listener.rs

parsec_service/front/
listener.rs
