//! Messages sent over Tor channels

//!

//! A 'channel' is a direct connection between a tor client and a

//! relay, or between two relays.  Current channels all use TLS.

//!

//! This module implements the [ChanCell] type, which is the encoding for

//! data sent over a channel.  It also encodes and decodes various

//! channel messages, which are the types of data conveyed over a

//! channel.

pub mod codec;

pub mod msg;

use std::num::NonZeroU32;

use caret::caret_int;

use derive_deftly::Deftly;

use tor_memquota::{derive_deftly_template_HasMemoryCost, HasMemoryCostStructural};

/// The amount of data sent in a fixed-length cell.

///

/// Historically, this was set at 509 bytes so that cells would be

/// 512 bytes long once commands and circuit IDs were added.  But since

/// protocol version 4, circuit IDs are 2 bytes longer, so cells are

/// now 514 bytes.

pub const CELL_DATA_LEN: usize = 509;

/// A cell body considered as a raw array of bytes

pub type RawCellBody = [u8; CELL_DATA_LEN];

/// A [`RawCellBody`] stored on the heap.

///

/// We use this often to avoid copying cell bodies around.

pub type BoxedCellBody = Box<RawCellBody>;

/// Channel-local identifier for a circuit.

///

/// A circuit ID can be 2 or 4 bytes long; since version 4 of the Tor

/// protocol, it's 4 bytes long.

///

/// Cannot be zero. For an "optional" circuit ID, use `Option<CircId>`.

#[derive(Copy, Clone, PartialEq, Eq, Debug, Hash)]

pub struct CircId(NonZeroU32);

impl From<NonZeroU32> for CircId {

}

impl From<CircId> for u32 {

}

impl std::fmt::Display for CircId {

}

impl CircId {

    /// Creates a `CircId` for non-zero `val`.

    ///

    /// Returns `None` when `val` is zero. Messages with a zero/None circuit ID

    /// apply to the channel as a whole.

    /// Convenience function to convert to a `u32`; `None` is mapped to 0.

        }

}

caret_int! {

    /// A ChanCmd is the type of a channel cell.  The value of the ChanCmd

    /// indicates the meaning of the cell, and (possibly) its length.

    #[derive(Deftly)]

    #[derive_deftly(HasMemoryCost)]

    pub struct ChanCmd(u8) {

        /// A fixed-length cell that will be dropped.

        PADDING = 0,

        /// Create a new circuit (obsolete format)

        CREATE = 1,

        /// Finish circuit-creation handshake (obsolete format)

        CREATED = 2,

        /// Relay cell, transmitted over a circuit.

        RELAY = 3,

        /// Destroy a circuit

        DESTROY = 4,

        /// Create a new circuit (no public-key)

        CREATE_FAST = 5,

        /// Finish a circuit-creation handshake (no public-key)

        CREATED_FAST = 6,

        // note gap in numbering: 7 is grouped with the variable-length cells

        /// Finish a channel handshake with time and address information

        NETINFO = 8,

        /// Relay cell, transmitted over a circuit.  Limited.

        RELAY_EARLY = 9,

        /// Create a new circuit (current format)

        CREATE2 = 10,

        /// Finish a circuit-creation handshake (current format)

        CREATED2 = 11,

        /// Adjust channel-padding settings

        PADDING_NEGOTIATE = 12,

        /// Variable-length cell, despite its number: negotiate versions

        VERSIONS = 7,

        /// Variable-length channel-padding cell

        VPADDING = 128,

        /// Provide additional certificates beyond those given in the TLS

        /// handshake

        CERTS = 129,

        /// Challenge material used in relay-to-relay handshake.

        AUTH_CHALLENGE = 130,

        /// Response material used in relay-to-relay handshake.

        AUTHENTICATE = 131,

        /// Indicates client permission to use relay.  Not currently used.

        AUTHORIZE = 132,

    }

}

/// Possible requirements on circuit IDs for a channel command.

enum CircIdReq {

    /// indicates a command that only takes a zero-valued circuit ID

    WantNone,

    /// indicates a command that only takes a nonzero-valued circuit ID

    WantSome,

    /// indicates a command that can take any circuit ID

    Any,

}

impl ChanCmd {

    /// Return true if this command is for a cell using the

    /// variable-length format.

    /// Return what kind of circuit ID this command expects.

            ChanCmd::PADDING

            | ChanCmd::NETINFO

            | ChanCmd::PADDING_NEGOTIATE

            | ChanCmd::VERSIONS

            | ChanCmd::VPADDING

            | ChanCmd::CERTS

            | ChanCmd::AUTH_CHALLENGE

            ChanCmd::CREATE

            | ChanCmd::CREATED

            | ChanCmd::RELAY

            | ChanCmd::DESTROY

            | ChanCmd::CREATE_FAST

            | ChanCmd::CREATED_FAST

            | ChanCmd::RELAY_EARLY

            | ChanCmd::CREATE2

        }

    /// Return true if this command is one that accepts the particular

    /// circuit ID `id`.

        }

}

/// A decoded and parsed channel cell of unrestricted type.

pub type AnyChanCell = ChanCell<msg::AnyChanMsg>;

/// Trait implemented by anything that can serve as a channel message.

///

/// Typically, this will be [`AnyChanMsg`](msg::AnyChanMsg) (to represent an unrestricted relay

/// message), or some restricted subset of those messages.

pub trait ChanMsg {

    /// Return the [`ChanCmd`] for this message.

    fn cmd(&self) -> ChanCmd;

    /// Write the body of this message (not including length or command).

    fn encode_onto<W: tor_bytes::Writer + ?Sized>(self, w: &mut W) -> tor_bytes::EncodeResult<()>;

    /// Decode this message from a given reader, according to a specified

    /// command value. The reader must be truncated to the exact length

    /// of the body.

    fn decode_from_reader(cmd: ChanCmd, r: &mut tor_bytes::Reader<'_>) -> tor_bytes::Result<Self>

    where

        Self: Sized;

}

/// A decoded channel cell, to be sent or received on a channel.

#[derive(Debug, Deftly)]

#[derive_deftly(HasMemoryCost)]

#[deftly(has_memory_cost(bounds = "M: HasMemoryCostStructural"))]

pub struct ChanCell<M> {

    /// Circuit ID associated with this cell, if any.

    #[deftly(has_memory_cost(copy))]

    circid: Option<CircId>,

    /// Underlying message in this cell

    msg: M,

}

impl<M: ChanMsg> ChanCell<M> {

    /// Construct a new channel cell.

    /// Return the circuit ID for this cell.

    /// Return a reference to the underlying message of this cell.

    /// Consume this cell and return its components.

}