//! A relay's view of the forward (away from the client, towards the exit) state of a circuit.

use crate::channel::{Channel, ChannelSender};

use crate::circuit::CircuitRxReceiver;

use crate::circuit::UniqId;

use crate::circuit::create::{Create2Wrap, CreateHandshakeWrap};

use crate::circuit::reactor::ControlHandler;

use crate::circuit::reactor::backward::BackwardReactorCmd;

use crate::circuit::reactor::forward::{ForwardCellDisposition, ForwardHandler};

use crate::circuit::reactor::hop_mgr::HopMgr;

use crate::crypto::cell::OutboundRelayLayer;

use crate::crypto::cell::RelayCellBody;

use crate::relay::RelayCircChanMsg;

use crate::util::err::ReactorError;

use crate::{Error, HopNum, Result};

// TODO(circpad): once padding is stabilized, the padding module will be moved out of client.

use crate::client::circuit::padding::QueuedCellPaddingInfo;

use crate::relay::channel_provider::{ChannelProvider, ChannelResult, OutboundChanSender};

use crate::relay::reactor::CircuitAccount;

use tor_cell::chancell::msg::{AnyChanMsg, Destroy, PaddingNegotiate, Relay};

use tor_cell::chancell::{AnyChanCell, BoxedCellBody, ChanMsg, CircId};

use tor_cell::relaycell::msg::{Extend2, Extended2, SendmeTag};

use tor_cell::relaycell::{RelayCellDecoderResult, RelayCellFormat, RelayCmd, UnparsedRelayMsg};

use tor_error::{internal, into_internal, warn_report};

use tor_linkspec::decode::Strictness;

use tor_linkspec::{OwnedChanTarget, OwnedChanTargetBuilder};

use tor_rtcompat::{Runtime, SpawnExt as _};

use futures::channel::mpsc;

use futures::{SinkExt as _, StreamExt as _, future};

use tracing::{debug, trace};

use std::result::Result as StdResult;

use std::sync::Arc;

use std::task::Poll;

/// Placeholder for our custom control message type.

type CtrlMsg = ();

/// Placeholder for our custom control command type.

type CtrlCmd = ();

/// The maximum number of RELAY_EARLY cells allowed on a circuit.

///

// TODO(relay): should we come up with a consensus parameter for this? (arti#2349)

const MAX_RELAY_EARLY_CELLS_PER_CIRCUIT: usize = 8;

/// Relay-specific state for the forward reactor.

pub(crate) struct Forward {

    /// An identifier for logging about this reactor's circuit.

    unique_id: UniqId,

    /// The outbound view of this circuit, if we are not the last hop.

    ///

    /// Delivers cells towards the exit.

    ///

    /// Only set for middle relays.

    outbound: Option<Outbound>,

    /// The cryptographic state for this circuit for inbound cells.

    crypto_out: Box<dyn OutboundRelayLayer + Send>,

    /// A handle to a [`ChannelProvider`], used for initiating outgoing Tor channels.

    ///

    /// Note: all circuit reactors of a relay need to be initialized

    /// with the *same* underlying Tor channel provider (`ChanMgr`),

    /// to enable the reuse of existing Tor channels where possible.

    chan_provider: Arc<dyn ChannelProvider<BuildSpec = OwnedChanTarget> + Send + Sync>,

    /// Whether we have received an EXTEND2 on this circuit.

    ///

    // TODO(relay): bools can be finicky.

    // Maybe we should combine this bool and the optional

    // outbound into a new state machine type

    // (with states Initial -> Extending -> Extended(Outbound))?

    // But should not do this if it turns out more convoluted than the bool-based approach.

    have_seen_extend2: bool,

    /// The number of RELAY_EARLY cells we have seen so far on this circuit.

    ///

    /// If we see more than [`MAX_RELAY_EARLY_CELLS_PER_CIRCUIT`] RELAY_EARLY cells, we tear down the circuit.

    relay_early_count: usize,

    /// A stream of events to be read from the main loop of the reactor.

    event_tx: mpsc::Sender<CircEvent>,

    /// Memory quota account

    memquota: CircuitAccount,

}

/// A type of event issued by the relay forward reactor.

pub(crate) enum CircEvent {

    /// The outcome of an EXTEND2 request.

    ExtendResult(StdResult<ExtendResult, ReactorError>),

}

/// A successful circuit extension result.

pub(crate) struct ExtendResult {

    /// The EXTENDED2 cell to send back to the client.

    extended2: Extended2,

    /// The outbound channel.

    outbound: Outbound,

    /// The reading end of the outbound Tor channel, if we are not the last hop.

    ///

    /// Yields cells moving from the exit towards the client, if we are a middle relay.

    outbound_chan_rx: CircuitRxReceiver,

}

/// The outbound view of a relay circuit.

struct Outbound {

    /// The circuit identifier on the outbound Tor channel.

    circ_id: CircId,

    /// The outbound Tor channel.

    channel: Arc<Channel>,

    /// The sending end of the outbound Tor channel.

    outbound_chan_tx: ChannelSender,

}

/// The outcome of `decode_relay_cell`.

enum CellDecodeResult {

    /// A decrypted cell.

    Recognized(SendmeTag, RelayCellDecoderResult),

    /// A cell we could not decrypt.

    Unrecognizd(RelayCellBody),

}

impl Forward {

    /// Create a new [`Forward`].

    /// Decode `cell`, returning its corresponding hop number, tag and decoded body.

        // Note: the client reactor will return the actual source hopnum

        };

        // The message is addressed to us! Now it's time to handle it...

            .inbound

    /// Handle a DROP message.

    #[allow(clippy::unnecessary_wraps)] // Returns Err if circ-padding is enabled

        cfg_if::cfg_if! {

            if #[cfg(feature = "circ-padding")] {

            } else {

                Ok(())

            }

        }

    /// Handle an EXTEND2 cell.

    ///

    /// This spawns a background task for dealing with the circuit extension,

    /// which then reports back the result via the [`Self::event_tx`] MPSC stream.

    /// Note that this MPSC stream is polled from the `ForwardReactor` main loop,

    /// and each `CircEvent` is passed back to [`Self::handle_event()`[ for handling.

        // TODO(relay): this should be allowed if the AllowNonearlyExtend consensus

        // param is set (arti#2349)

        // Check if we're in the right state before parsing the EXTEND2

        )

            object: "EXTEND2",

            // TODO: should we include the error in the circ proto error context?

        // Note: we don't do any further validation on the EXTEND2 here,

        // under the assumption it will be handled by the ChannelProvider.

        // TODO(relay): because we dispatch this the entire EXTEND2 handling to a background task,

        // we don't really need the channel provider to send us the outcome via an MPSC channel,

        // because get_or_launch() could simply be async (it wouldn't block the reactor,

        // because it runs in another task). Maybe we need to rethink the ChannelProvider API?

                // Discard the error if the reactor shut down before we had

                // a chance to complete the extend handshake

    /// Handle the outcome of handling an EXTEND2.

        let ExtendResult {

    /// Extend this circuit on the channel received on `chan_rx`.

    ///

    /// Note: this gets spawned in a background task from

    /// [`Self::handle_extend2`] so as not to block the reactor main loop.

    ///

    #[allow(unused_variables)] // will become used once we implement CREATED2 timeouts

        // We expect the channel build timeout to be enforced by the ChannelProvider

                // Note: retries are handled within

                // get_or_launch(), so if we receive an

                // error at this point, we need to bail

            }

        };

            circ_id = %unique_id,

        );

        // Now that we finally have a forward Tor channel,

        // it's time to forward the onion skin and extend the circuit...

        //

        // Note: the only reason we need to await here is because internally

        // new_outbound_circ() sends a control message to the channel reactor handles,

        // which is handled asynchronously. In practice, we're not actually waiting on

        // the network here, so in theory we shouldn't need a timeout for this operation.

        // We have allocated a circuit in the channel's circmap,

        // now it's time to send the CREATE2 and wait for the response.

        // Time to write the CREATE2 to the outbound channel...

            circ_id = %unique_id,

        );

        // TODO(relay): we need a timeout here, otherwise we might end up waiting forever

        // for the CREATED2 to arrive.

        //

        // There is some complexity here, see

        // https://gitlab.torproject.org/tpo/core/arti/-/merge_requests/3648#note_3340125

            circ_id = %unique_id,

        );

        // If we reach this point, it means we have extended

        // the circuit by one hop, so we need to take the contents

        // of the CREATE/CREATED2 cell, and package an EXTEND/EXTENDED2

        // to send back to the client.

    /// Handle a RELAY or RELAY_EARLY cell.

            }

        };

    /// Handle a forward cell that we could not decrypt.

        // TODO(relay): remove this log once we add some tests

        // and confirm relaying cells works as expected

        // (in practice it will be too noisy to be useful, even at trace level).

            circ_id = %self.unique_id,

        );

            // The client shouldn't try to send us any cells before it gets

            // an EXTENDED2 cell from us

        };

        } else {

        };

        // Note: this future is always `Ready`, because we checked the sink for readiness

        // before polling the input channel, so await won't block.

    /// Handle a TRUNCATE cell.

    #[allow(clippy::unused_async)] // TODO(relay)

        // TODO(relay): when we implement this, we should try to do better than C Tor:

        // if we have some cells queued for the next hop in the circuit,

        // we should try to flush them *before* tearing it down.

        //

        // See https://gitlab.torproject.org/tpo/core/arti/-/merge_requests/3487#note_3296035

    /// Handle a DESTROY cell originating from the client.

    #[allow(clippy::needless_pass_by_value)] // TODO(relay)

    /// Handle a PADDING_NEGOTIATE cell originating from the client.

    #[allow(clippy::needless_pass_by_value)] // TODO(relay)

}

impl ForwardHandler for Forward {

    type BuildSpec = OwnedChanTarget;

    type CircChanMsg = RelayCircChanMsg;

    type CircEvent = CircEvent;

        }

        use RelayCircChanMsg::*;

            }

            }

        }

        }

            }

            None => {

                // Pedantically, if the channel doesn't exist, it can't be ready,

                // but we have no choice here than to return Ready

                // (returning Pending would cause the reactor to lock up).

                //

                // Returning ready here means the base reactor is allowed to read

                // from its inbound channel. This is OK, because if we *do*

                // read a cell from that channel and find ourselves needing to

                // forward it to the next hop, we simply return a proto violation error,

                // shutting down the reactor.

            }

}

impl ControlHandler for Forward {

    type CtrlMsg = CtrlMsg;

    type CtrlCmd = CtrlCmd;

}

impl Drop for Forward {

}