coap_connection.h

// Copyright 2024-2025 The Aerospace Corporation.
// This file is a part of SatCat5, licensed under CERN-OHL-W v2 or later.
// CoAP request/response handling for a single client-server connection
 
#pragma once
 
#include <satcat5/ccsds_spp.h>
#include <satcat5/coap_constants.h>
#include <satcat5/udp_core.h>
 
// Maximum outgoing message size, excluding Eth/IP/UDP overhead.
// Default matches the recommended maximum from Section 4.6.
#ifndef SATCAT5_COAP_BUFFSIZE
#define SATCAT5_COAP_BUFFSIZE 1152
#endif
 
// Store a record of the last N received requests (Msg ID + token).
// Allows detection of new requests without assuming sequential IDs.
// Stale out-of-order deliveries must not exceed this upper bound.
#ifndef SATCAT5_COAP_HISTORY
#define SATCAT5_COAP_HISTORY 4
#endif
 
namespace satcat5 {
    namespace coap {
        class Connection
            : protected satcat5::net::Protocol
            , protected satcat5::poll::Timer
            , protected satcat5::io::ArrayWriteStatic<SATCAT5_COAP_BUFFSIZE>
        {
        public:
            // Accessors for the cache state.
            inline bool is_idle() const         
                { return m_state == State::IDLE && m_allow_reuse; }
            inline bool is_match_addr() const   
                { return m_addr->matches_reply_address(); }
            bool is_match_coap(                 
                const satcat5::coap::ReadHeader* msg) const;
            bool is_match_reuse() const;        
            inline bool is_await() const        
                { return m_state == State::WAIT_RESPONSE_U
                      || m_state == State::WAIT_RESPONSE_M
                      || m_state == State::RESPONSE_SEP1;}
            inline bool is_connecting() const   
                { return m_state == State::CONNECT_IDLE
                      || m_state == State::CONNECT_BUSY; }
            inline bool is_request() const      
                { return m_state == State::REQUEST_CON
                      || m_state == State::REQUEST_NON
                      || m_state == State::REQUEST_SEP; }
            inline bool is_response() const     
                { return m_state == State::RESPONSE_CACHE
                      || m_state == State::RESPONSE_DEFER
                      || m_state == State::RESPONSE_SEP1
                      || m_state == State::RESPONSE_SEP2; }
            inline bool is_separate() const     
                { return m_state == State::RESPONSE_SEP1
                      || m_state == State::RESPONSE_SEP2; }
            inline u16 msg_id() const           
                { return m_msgid[m_meta_idx]; }
            inline u64 token() const            
                { return m_token[m_meta_idx]; }
            inline u8 tkl() const               
                { return m_flags[m_meta_idx] & 0x0F; }
 
            void close();
 
            // Child class SHOULD implement a connect(...) method that
            // sets connection parameters for outgoing requests.  That
            // method must call connected() to update the parent state.
            // (See examples ConnectionSpp and ConnectionUdp, below.)
            // Connections in this state remain open until explicitly
            // closed, and are not reused even if they appear to be idle.
 
            bool ping(u16 msg_id);
 
            inline u32 get_proxy_token() const
                { return m_proxy_token; }
 
            inline void set_proxy_token(u32 token)
                { m_proxy_token = token; }
 
            bool ready() const;
 
            satcat5::io::Writeable* open_request();
 
            satcat5::io::Writeable* open_response();
 
            bool open_separate(const satcat5::coap::ReadHeader* msg);
 
            satcat5::io::Writeable* continue_separate();
 
            inline satcat5::io::Writeable* open_response_auto()
                { return is_separate() ? continue_separate() : open_response(); }
 
            bool error_response(satcat5::coap::Code code, const char* why = 0);
 
            u8 response_type() const;
 
            bool test_inject(unsigned len, const void* data);
 
        protected:
            Connection(
                satcat5::coap::Endpoint* endpoint,
                satcat5::net::Address* addr);
            ~Connection() SATCAT5_OPTIONAL_DTOR;
 
            void init(satcat5::coap::Endpoint* endpoint);
 
            // External event handling.
            friend satcat5::coap::Endpoint;
            bool deliver(satcat5::coap::Reader* msg);
            void frame_rcvd(satcat5::io::LimitedRead& src) override;
            void timer_event() override;
            bool write_finalize() override;
 
            // Internal event handling.
            bool connected(bool allow_reuse);
            void error_event();
            int match_history(const satcat5::coap::ReadHeader* msg) const;
            void push_history(const satcat5::coap::ReadHeader* msg);
            void reset_hard();
            void reset_soft();
            bool send_buffer();
            bool send_empty(u8 typ, u16 id);
            bool send_first();
            void timer_rand(u32 base_msec);
 
            // Internal state.
            enum class State {
                IDLE,               // Idle
                ERROR,              // Error-handling in progress
                CONNECT_IDLE,       // Connection in progress, otherwise idle
                CONNECT_BUSY,       // Connection in progress, transmit once ready
                WAIT_RESPONSE_U,    // Unicast request received, awaiting response
                WAIT_RESPONSE_M,    // Multicast request received, awaiting response
                REQUEST_CON,        // Confirmable request with timed retransmit
                REQUEST_NON,        // Nonconfirmable request without retransmit
                REQUEST_SEP,        // Waiting to receive part 2 of separated response
                RESPONSE_CACHE,     // Standard response with cached retransmit
                RESPONSE_DEFER,     // Delayed response to multicast query
                RESPONSE_SEP1,      // Waiting to send separated response
                RESPONSE_SEP2};     // Waiting for ACK to separated response
            satcat5::coap::Endpoint* m_coap;        // Client or server
            satcat5::net::Address* const m_addr;    // Remote address object
            State m_state;                          // Connection state
            u32 m_proxy_token;                      // Reverse-proxy identifier
            u8 m_allow_reuse;                       // Ephemeral connection?
            u8 m_tx_count;                          // Transmission count
            u8 m_meta_idx;                          // History write index [0..N)
            u8 m_meta_count;                        // History depth [0..N]
            u8 m_flags[SATCAT5_COAP_HISTORY];       // History of transaction flags
            u16 m_msgid[SATCAT5_COAP_HISTORY];      // History of message IDs
            u64 m_token[SATCAT5_COAP_HISTORY];      // History of tokens (0-8 bytes)
 
        private:
            // Linked list of other Connection objects.
            friend satcat5::util::ListCore;
            satcat5::coap::Connection* m_next;
        };
 
        class ConnectionSpp final : public satcat5::coap::Connection {
        public:
            ConnectionSpp(
                satcat5::coap::Endpoint* endpoint,
                satcat5::ccsds_spp::Dispatch* iface);
 
            bool connect(u16 apid);
 
        private:
            satcat5::ccsds_spp::Address m_spp;
        };
 
        class ConnectionUdp final : public satcat5::coap::Connection {
        public:
            ConnectionUdp(
                satcat5::coap::Endpoint* endpoint,
                satcat5::udp::Dispatch* iface)
                : Connection(endpoint, &m_udp), m_udp(iface) {}
 
            ConnectionUdp()
                : Connection(nullptr, &m_udp), m_udp(nullptr) {}
 
            void init(
                satcat5::coap::Endpoint* endpoint,
                satcat5::udp::Dispatch* iface);
 
            bool connect(
                const satcat5::udp::Addr& dstaddr,
                const satcat5::udp::Port& dstport = satcat5::udp::PORT_COAP,
                const satcat5::udp::Port& srcport = satcat5::udp::PORT_NONE,
                bool allow_reuse = false);
 
            bool is_match_addr(
                const satcat5::udp::Addr& dstaddr,
                const satcat5::udp::Port& dstport) const;
 
            satcat5::udp::Address m_udp;
        };
 
        template <unsigned SIZE>
        class ConnectionUdpArray final {
        public:
            ConnectionUdpArray(
                satcat5::coap::Endpoint* endpoint,
                satcat5::udp::Dispatch* iface)
                : m_array{} // Use default constructor
            {
                for (unsigned a = 0 ; a < SIZE ; ++a) {
                    m_array[a].init(endpoint, iface);
                }
            }
 
            inline ConnectionUdp& operator[](unsigned idx)
                { return m_array[idx]; }
 
        private:
            satcat5::coap::ConnectionUdp m_array[SIZE];
        };
    }
}