//! Encoding and decoding for relay messages

//!

//! Relay messages are sent along circuits, inside RELAY or RELAY_EARLY

//! cells.

use super::{RelayCellFormat, RelayCmd};

use crate::chancell::msg::{

    DestroyReason, HandshakeType, TAP_C_HANDSHAKE_LEN, TAP_S_HANDSHAKE_LEN,

};

use crate::chancell::CELL_DATA_LEN;

use caret::caret_int;

use derive_deftly::Deftly;

use std::fmt::Write;

use std::net::{IpAddr, Ipv4Addr};

use std::num::NonZeroU8;

use tor_bytes::{EncodeError, EncodeResult, Error, Result};

use tor_bytes::{Readable, Reader, Writeable, Writer};

use tor_linkspec::EncodedLinkSpec;

use tor_llcrypto::pk::rsa::RsaIdentity;

use tor_llcrypto::util::ct::CtByteArray;

use tor_memquota::{derive_deftly_template_HasMemoryCost, memory_cost_structural_copy};

use bitflags::bitflags;

#[cfg(feature = "conflux")]

#[cfg_attr(docsrs, doc(cfg(feature = "conflux")))]

pub use super::conflux::{ConfluxLink, ConfluxLinked, ConfluxLinkedAck, ConfluxSwitch};

#[cfg(feature = "flowctl-cc")]

#[cfg_attr(docsrs, doc(cfg(feature = "flowctl-cc")))]

use super::flow_ctrl::{Xoff, Xon};

#[cfg(feature = "hs")]

#[cfg_attr(docsrs, doc(cfg(feature = "hs")))]

pub use super::hs::{

    est_intro::EstablishIntro, EstablishRendezvous, IntroEstablished, Introduce1, Introduce2,

    IntroduceAck, Rendezvous1, Rendezvous2, RendezvousEstablished,

};

#[cfg(feature = "experimental-udp")]

#[cfg_attr(docsrs, doc(cfg(feature = "experimental-udp")))]

pub use super::udp::{ConnectUdp, ConnectedUdp, Datagram};

crate::restrict::restricted_msg! {

/// A single parsed relay message, sent or received along a circuit

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(HasMemoryCost)]

#[non_exhaustive]

@omit_from "avoid_conflict_with_a_blanket_implementation"

pub enum AnyRelayMsg : RelayMsg {

    /// Create a stream

    Begin,

    /// Send data on a stream

    Data,

    /// Close a stream

    End,

    /// Successful response to a Begin message

    Connected,

    /// For flow control

    Sendme,

    /// Extend a circuit to a new hop (deprecated)

    Extend,

    /// Successful response to an Extend message (deprecated)

    Extended,

    /// Extend a circuit to a new hop

    Extend2,

    /// Successful response to an Extend2 message

    Extended2,

    /// Partially close a circuit

    Truncate,

    /// Tell the client that a circuit has been partially closed

    Truncated,

    /// Used for padding

    Drop,

    /// Launch a DNS request

    Resolve,

    /// Response to a Resolve message

    Resolved,

    /// Start a directory stream

    BeginDir,

    /// Start a UDP stream.

    [feature = "experimental-udp"]

    ConnectUdp,

    /// Successful response to a ConnectUdp message

    [feature = "experimental-udp"]

    ConnectedUdp,

    /// UDP stream data

    [feature = "experimental-udp"]

    Datagram,

    /// Link circuits together at the receiving endpoint

    [feature = "conflux"]

    ConfluxLink,

    /// Confirm that the circuits were linked

    [feature = "conflux"]

    ConfluxLinked,

    /// Acknowledge the linkage of the circuits, for RTT measurement.

    [feature = "conflux"]

    ConfluxLinkedAck,

    /// Switch to another leg in an already linked circuit construction.

    [feature = "conflux"]

    ConfluxSwitch,

    /// Update a stream's transmit rate limit.

    [feature = "flowctl-cc"]

    Xon,

    /// Disable transmitting on a stream.

    [feature = "flowctl-cc"]

    Xoff,

    /// Establish Introduction

    [feature = "hs"]

    EstablishIntro,

    /// Establish Rendezvous

    [feature = "hs"]

    EstablishRendezvous,

    /// Introduce1 (client to introduction point)

    [feature = "hs"]

    Introduce1,

    /// Introduce2 (introduction point to service)

    [feature = "hs"]

    Introduce2,

    /// Rendezvous1 (service to rendezvous point)

    [feature = "hs"]

    Rendezvous1,

    /// Rendezvous2 (rendezvous point to client)

    [feature = "hs"]

    Rendezvous2,

    /// Acknowledgement for EstablishIntro.

    [feature = "hs"]

    IntroEstablished,

    /// Acknowledgment for EstablishRendezvous.

    [feature = "hs"]

    RendezvousEstablished,

    /// Acknowledgement for Introduce1.

    [feature = "hs"]

    IntroduceAck,

    _ =>

    /// An unrecognized command.

    Unrecognized,

    }

}

/// Internal: traits in common different cell bodies.

pub trait Body: Sized {

    /// Decode a relay cell body from a provided reader.

    fn decode_from_reader(r: &mut Reader<'_>) -> Result<Self>;

    /// Encode the body of this cell into the end of a writer.

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

}

bitflags! {

    /// A set of recognized flags that can be attached to a begin cell.

    ///

    /// For historical reasons, these flags are constructed so that 0

    /// is a reasonable default for all of them.

    #[derive(Clone, Copy, Debug)]

    pub struct BeginFlags : u32 {

        /// The client would accept a connection to an IPv6 address.

        const IPV6_OKAY = (1<<0);

        /// The client would not accept a connection to an IPv4 address.

        const IPV4_NOT_OKAY = (1<<1);

        /// The client would rather have a connection to an IPv6 address.

        const IPV6_PREFERRED = (1<<2);

    }

}

memory_cost_structural_copy!(BeginFlags);

impl From<u32> for BeginFlags {

}

/// A preference for IPv4 vs IPv6 addresses; usable as a nicer frontend for

/// BeginFlags.

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

#[non_exhaustive]

pub enum IpVersionPreference {

    /// Only IPv4 is allowed.

    Ipv4Only,

    /// IPv4 and IPv6 are both allowed, and IPv4 is preferred.

    #[default]

    Ipv4Preferred,

    /// IPv4 and IPv6 are both allowed, and IPv6 is preferred.

    Ipv6Preferred,

    /// Only IPv6 is allowed.

    Ipv6Only,

}

impl From<IpVersionPreference> for BeginFlags {

        use IpVersionPreference::*;

        }

}

/// A Begin message creates a new data stream.

///

/// Upon receiving a Begin message, relays should try to open a new stream

/// for the client, if their exit policy permits, and associate it with a

/// new TCP connection to the target address.

///

/// If the exit decides to reject the Begin message, or if the TCP

/// connection fails, the exit should send an End message.

///

/// Clients should reject these messages.

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Begin {

    /// Ascii string describing target address

    addr: Vec<u8>,

    /// Target port

    port: u16,

    /// Flags that describe how to resolve the address

    flags: BeginFlags,

}

impl Begin {

    /// Construct a new Begin cell

    /// Return the address requested in this message.

    /// Return the port requested by this message.

    /// Return the set of flags provided in this message.

}

impl Body for Begin {

                // IPv6 address

            } else {

                // IPv4 address, or hostname.

            }

        };

}

/// A Data message represents data sent along a stream.

///

/// Upon receiving a Data message for a live stream, the client or

/// exit sends that data onto the associated TCP connection.

///

/// These messages hold between 1 and [Data::MAXLEN] bytes of data each;

/// they are the most numerous messages on the Tor network.

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Data {

    /// Contents of the cell, to be sent on a specific stream

    ///

    /// INVARIANT: Holds between 1 and [`Data::MAXLEN`] bytes, inclusive.

    //

    // TODO: There's a good case to be made that this should be a BoxedCellBody

    // instead, to avoid allocations and copies.  But first probably we should

    // figure out how proposal 340 will work with this.  Possibly, we will wind

    // up using `bytes` or something.

    body: Vec<u8>,

}

impl Data {

    /// The longest allowable body length for a single V0 data cell.

    ///

    /// Relay command (1) + 'Recognized' (2) + StreamID (2) + Digest (4) + Length (2) = 11

    pub const MAXLEN_V0: usize = CELL_DATA_LEN - 11;

    /// The longest allowable body length for a single V1 data cell.

    ///

    /// Tag (16) + Relay command (1) + Length (2) + StreamID (2) = 21

    pub const MAXLEN_V1: usize = CELL_DATA_LEN - 21;

    /// The longest allowable body length for any data cell.

    ///

    /// Note that this value is too large to fit into a v1 relay cell;

    /// see [`MAXLEN_V1`](Data::MAXLEN_V1) if you are making a v1 data cell.

    ///

    pub const MAXLEN: usize = Data::MAXLEN_V0;

    /// Construct a new data cell.

    ///

    /// Returns an error if `inp` is longer than [`Data::MAXLEN`] bytes.

    /// Construct a new data cell, taking as many bytes from `inp`

    /// as possible.

    ///

    /// Return the data cell, and a slice holding any bytes that

    /// wouldn't fit (if any).

    ///

    /// Returns None if the input was empty.

    /// Construct a new data cell from a provided vector of bytes.

    ///

    /// The vector _must_ not have more than [`Data::MAXLEN`] bytes, and must

    /// not be empty.

    /// Return the maximum allowable body length for a Data message

    /// using the provided `format`.

        }

}

impl From<Data> for Vec<u8> {

}

impl AsRef<[u8]> for Data {

}

impl Body for Data {

        })

}

/// An End message tells the other end of the circuit to close a stream.

///

/// Note that End messages do not implement a true half-closed state,

/// so after sending an End message each party needs to wait a while

/// to be sure that the stream is completely dead.

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct End {

    /// Reason for closing the stream

    reason: EndReason,

    /// If the reason is EXITPOLICY, this holds the resolved address an

    /// associated TTL.  The TTL is set to MAX if none was given.

    addr: Option<(IpAddr, u32)>,

}

caret_int! {

    /// A declared reason for closing a stream

    #[derive(Deftly)]

    #[derive_deftly(HasMemoryCost)]

    pub struct EndReason(u8) {

        /// Closing a stream because of an unspecified reason.

        ///

        /// This is the only END reason that clients send.

        MISC = 1,

        /// Couldn't look up hostname.

        RESOLVEFAILED = 2,

        /// Remote host refused connection.

        CONNECTREFUSED = 3,

        /// Closing a stream because of an exit-policy violation.

        EXITPOLICY = 4,

        /// Circuit destroyed

        DESTROY = 5,

        /// Anonymized TCP connection was closed

        DONE = 6,

        /// Connection timed out, or OR timed out while connecting

        TIMEOUT = 7,

        /// No route to target destination.

        NOROUTE = 8,

        /// OR is entering hibernation and not handling requests

        HIBERNATING = 9,

        /// Internal error at the OR

        INTERNAL = 10,

        /// Ran out of resources to fulfill requests

        RESOURCELIMIT = 11,

        /// Connection unexpectedly reset

        CONNRESET = 12,

        /// Tor protocol violation

        TORPROTOCOL = 13,

        /// BEGIN_DIR cell at a non-directory-cache.

        NOTDIRECTORY = 14,

    }

}

impl tor_error::HasKind for EndReason {

        use tor_error::ErrorKind as EK;

        use EndReason as E;

        }

}

impl End {

    /// Make a new END_REASON_MISC message.

    ///

    /// Clients send this every time they decide to close a stream.

    /// Make a new END message with the provided end reason.

    /// Make a new END message with END_REASON_EXITPOLICY, and the

    /// provided address and ttl.

    /// Return the provided EndReason for this End cell.

}

impl Body for End {

                _ => {

                    // Ignores other message lengths.

                }

            };

            } else {

            };

        } else {

        }

            }

}

impl From<EndReason> for std::io::ErrorKind {

        use std::io::ErrorKind::*;

        }

}

/// A Connected message is a successful response to a Begin message

///

/// When an outgoing connection succeeds, the exit sends a Connected

/// back to the client.

///

/// Clients never send Connected messages.

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Connected {

    /// Resolved address and TTL (time to live) in seconds

    addr: Option<(IpAddr, u32)>,

}

impl Connected {

    /// Construct a new empty connected cell.

    /// Construct a connected cell with an address and a time-to-live value.

}

impl Body for Connected {

        } else {

        };

                }

            }

}

/// An authentication tag to use for circuit-level SENDME messages.

///

/// It is either a 20-byte tag (used with Tor1 encryption),

/// or a 16-byte tag (used with CGO encryption).

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

#[derive_deftly(HasMemoryCost)]

pub struct SendmeTag {

    /// The number of bytes present in the tag.

    /// Always equal to 16 or 20.

    ///

    /// We use a NonZeroU8 here so Rust can use its niche optimization.

    len: NonZeroU8,

    /// The actual contents of the tag.

    ///

    /// Tags above 20 bytes long are always an error.

    ///

    /// Unused bytes are always set to zero, so we can derive PartialEq.

    tag: CtByteArray<20>,

}

impl From<[u8; 20]> for SendmeTag {

    // In experimentation, these "inlines" were necessary for good generated asm.

    #[inline]

}

impl From<[u8; 16]> for SendmeTag {

    // In experimentation, these "inlines" were necessary for good generated asm.

    #[inline]

}

impl AsRef<[u8]> for SendmeTag {

}

/// An error from attempting to decode a SENDME tag.

#[derive(Clone, Debug, thiserror::Error)]

#[non_exhaustive]

#[error("Invalid size {} on SENDME tag", len)]

pub struct InvalidSendmeTag {

    /// The length of the invalid tag.

    len: usize,

}

impl From<InvalidSendmeTag> for tor_bytes::Error {

}

impl<'a> TryFrom<&'a [u8]> for SendmeTag {

    type Error = InvalidSendmeTag;

    // In experimentation, this "inline" was especially necessary for good generated asm.

    #[inline]

            16 => {

            }

            20 => {

            }

        }

}

/// A Sendme message is used to increase flow-control windows.

///

/// To avoid congestion, each Tor circuit and stream keeps track of a

/// number of data cells that it is willing to send.  It decrements

/// these numbers every time it sends a cell.  If these numbers reach

/// zero, then no more cells can be sent on the stream or circuit.

///

/// The only way to re-increment these numbers is by receiving a

/// Sendme cell from the other end of the circuit or stream.

///

/// For security, current circuit-level Sendme cells include an

/// authentication tag that proves knowledge of the cells that they are

/// acking.

///

/// See [tor-spec.txt](https://spec.torproject.org/tor-spec) for more

/// information; also see the source for `tor_proto::circuit::sendme`.

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Sendme {

    /// A tag value authenticating the previously received data.

    tag: Option<SendmeTag>,

}

impl Sendme {

    /// Return a new empty sendme cell

    ///

    /// This format is used on streams, and on circuits without sendme

    /// authentication.

    /// This format is used on circuits with sendme authentication.

    /// Consume this cell and return its authentication tag, if any

}

impl From<SendmeTag> for Sendme {

}

impl Body for Sendme {

        } else {

                1 => {

                }

                _ => {

                }

            }

        };

            }

        }

}

/// Extend was an obsolete circuit extension message format.

///

/// This format only handled IPv4 addresses, RSA identities, and the

/// TAP handshake.  Modern Tor clients use Extend2 instead.

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Extend {

    /// Where to extend to (address)

    addr: Ipv4Addr,

    /// Where to extend to (port)

    port: u16,

    /// A TAP handshake to send

    handshake: Vec<u8>,

    /// The RSA identity of the target relay

    rsaid: RsaIdentity,

}

impl Extend {

    /// Construct a new (deprecated) extend cell

}

impl Body for Extend {

}

/// Extended was an obsolete circuit extension message, sent in reply to

/// an Extend message.

///

/// Like Extend, the Extended message was only designed for the TAP

/// handshake.

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Extended {

    /// Contents of the handshake sent in response to the EXTEND

    handshake: Vec<u8>,

}

impl Extended {

    /// Construct a new Extended message with the provided handshake

}

impl Body for Extended {

}

/// An Extend2 message tells the last relay in a circuit to extend to a new

/// hop.

///

/// When a relay (call it R) receives an Extend2 message, it tries to

/// find (or make) a channel to the other relay (R') described in the

/// list of link specifiers. (A link specifier can be an IP addresses

/// or a cryptographic identity).  Once R has such a channel, the

/// it packages the client's handshake data as a new Create2 message

/// R'.  If R' replies with a Created2 (success) message, R packages

/// that message's contents in an Extended message.

//

/// Unlike Extend messages, Extend2 messages can encode any handshake

/// type, and can describe relays in ways other than IPv4 addresses

/// and RSA identities.

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Extend2 {

    /// A vector of "link specifiers"

    ///

    /// These link specifiers describe where to find the target relay

    /// that the recipient should extend to.  They include things like

    /// IP addresses and identity keys.

    linkspec: Vec<EncodedLinkSpec>,

    /// Type of handshake to be sent in a CREATE2 cell

    handshake_type: HandshakeType,

    /// Body of the handshake to be sent in a CREATE2 cell

    handshake: Vec<u8>,

}

impl Extend2 {

    /// Create a new Extend2 cell.

    /// Return the type of this handshake.

    /// Return the inner handshake for this Extend2 cell.

}

impl Body for Extend2 {

        }

}

/// Extended2 is a successful reply to an Extend2 message.

///

/// Extended2 messages are generated by the former last hop of a

/// circuit, to tell the client that they have successfully completed

/// a handshake on the client's behalf.

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Extended2 {

    /// Contents of the CREATED2 cell that the new final hop sent in

    /// response

    handshake: Vec<u8>,

}

impl Extended2 {

    /// Construct a new Extended2 message with the provided handshake

    /// Consume this extended2 cell and return its body.

}

impl Body for Extended2 {

}

/// A Truncated message is sent to the client when the remaining hops

/// of a circuit have gone away.

///

/// NOTE: Current Tor implementations often treat Truncated messages and

/// Destroy messages interchangeably.  Truncated was intended to be a

/// "soft" Destroy, that would leave the unaffected parts of a circuit

/// still usable.

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Truncated {

    /// Reason for which this circuit was truncated.

    reason: DestroyReason,

}

impl Truncated {

    /// Construct a new truncated message.

    /// Get the provided reason to truncate the circuit.

}

impl Body for Truncated {

        })

}

/// A Resolve message launches a DNS lookup stream.

///

/// A client sends a Resolve message when it wants to perform a DNS

/// lookup _without_ connecting to the resulting address.  On success

/// the exit responds with a Resolved message; on failure it responds

/// with an End message.

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Resolve {

    /// Ascii-encoded address to resolve

    query: Vec<u8>,

}

impl Resolve {

    /// Construct a new resolve message to look up a hostname.

    /// Construct a new resolve message to do a reverse lookup on an address

            }

            }

        };

}

impl Body for Resolve {

}

/// Possible response to a DNS lookup

#[derive(Debug, Clone, Eq, PartialEq, Deftly)]

#[derive_deftly(HasMemoryCost)]

#[non_exhaustive]

pub enum ResolvedVal {

    /// We found an IP address

    Ip(IpAddr),

    /// We found a hostname

    Hostname(Vec<u8>),

    /// Error; try again

    TransientError,

    /// Error; don't try again

    NontransientError,

    /// A DNS lookup response that we didn't recognize

    Unrecognized(u8, Vec<u8>),

}

/// Indicates a hostname response

const RES_HOSTNAME: u8 = 0;

/// Indicates an IPv4 response

const RES_IPV4: u8 = 4;

/// Indicates an IPv6 response

const RES_IPV6: u8 = 6;

/// Transient error (okay to try again)

const RES_ERR_TRANSIENT: u8 = 0xF0;

/// Non-transient error (don't try again)

const RES_ERR_NONTRANSIENT: u8 = 0xF1;

impl Readable for ResolvedVal {

        /// Helper: return the expected length of a resolved answer with

        /// a given type, if there is a particular expected length.

            }

            RES_ERR_TRANSIENT => {

            }

            RES_ERR_NONTRANSIENT => {

            }

        })

}

impl Writeable for ResolvedVal {

            }

            }

            }

            }

        }

}

/// A Resolved message is a successful reply to a Resolve message.

///

/// The Resolved message contains a list of zero or more addresses,

/// and their associated times-to-live in seconds.

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Resolved {

    /// List of addresses and their associated time-to-live values.

    answers: Vec<(ResolvedVal, u32)>,

}

impl Resolved {

    /// Return a new empty Resolved object with no answers.

    /// Return a new Resolved object reporting a name lookup error.

    ///

    /// TODO: Is getting no answer an error; or it is represented by

    /// a list of no answers?

        } else {

        };

    /// Add a single answer to this Resolved message

    /// Consume this Resolved message, returning a vector of the

    /// answers and TTL values that it contains.

    ///

    /// Note that actually relying on these TTL values can be

    /// dangerous in practice, since the relay that sent the cell

    /// could be lying in order to cause more lookups, or to get a

    /// false answer cached for longer.

}

impl Body for Resolved {

        }

        }

}

/// A relay message that we didn't recognize

///

/// NOTE: Clients should generally reject these.

#[derive(Debug, Clone, Deftly)]

#[derive_deftly(HasMemoryCost)]

pub struct Unrecognized {

    /// Command that we didn't recognize

    cmd: RelayCmd,

    /// Body associated with that command

    body: Vec<u8>,

}

impl Unrecognized {

    /// Create a new 'unrecognized' cell.

    /// Return the command associated with this message

    /// Decode this message, using a provided command.

}

impl Body for Unrecognized {

        })

}