// SPDX-License-Identifier: BSD-2-Clause

/*

 * Copyright © The libcoap-rs Contributors, all rights reserved.

 * This file is part of the libcoap-rs project, see the README file for

 * general information on this project and the NOTICE.md and LICENSE files

 * for information regarding copyright ownership and terms of use.

 *

 * resource.rs - Types relating to CoAP resource management.

 */

//! Resource and resource handler descriptions

use core::ffi::c_int;

use std::{

    any::Any,

    cell::{Ref, RefMut},

    fmt::{Debug, Formatter},

    marker::PhantomData,

};

use libcoap_sys::{

    coap_add_attr, coap_delete_resource, coap_new_str_const, coap_pdu_t, coap_register_request_handler,

    coap_resource_get_uri_path, coap_resource_get_userdata, coap_resource_init, coap_resource_notify_observers,

    coap_resource_set_get_observable, coap_resource_set_mode, coap_resource_set_userdata, coap_resource_t,

    coap_send_rst, coap_session_t, coap_string_t, COAP_ATTR_FLAGS_RELEASE_NAME, COAP_ATTR_FLAGS_RELEASE_VALUE,

    COAP_RESOURCE_FLAGS_NOTIFY_CON, COAP_RESOURCE_FLAGS_NOTIFY_NON, COAP_RESOURCE_FLAGS_RELEASE_URI,

};

use crate::{

    context::ensure_coap_started,

    error::MessageConversionError,

    mem::{CoapFfiRcCell, DropInnerExclusively},

    message::{request::CoapRequest, response::CoapResponse, CoapMessage, CoapMessageCommon},

    protocol::{CoapMessageCode, CoapMessageType, CoapRequestCode},

    session::{CoapServerSession, CoapSessionCommon},

};

// Trait aliases are experimental

//trait CoapMethodHandlerFn<D> = FnMut(&D, &mut CoapSession, &CoapRequestMessage, &mut CoapResponseMessage);

// Some macro wizardry to statically wrap request handlers.

/// Create a CoapRequestHandler using the provided function.

///

/// This macro cannot be used if the intended handler function does not have a 'static lifetime,

/// i.e. if the handler function is a closure.

/// In these cases, use [CoapRequestHandler::new()] instead.

#[macro_export]

macro_rules! resource_handler {

    ($f:ident, $t:path) => {{

        #[allow(clippy::unnecessary_mut_passed)] // We don't know whether the function needs a mutable reference or not.

        unsafe { CoapRequestHandler::<$t>::from_raw_handler(_coap_method_handler_wrapper::<$t>) }

    }};

}

/// Converts the raw parameters provided to a request handler into the appropriate wrapped types.

///

/// If an error occurs while parsing the resource data, this function will send an RST message to the

/// client and return a [MessageConversionError].

///

/// This function is not intended for public use, the only reason it is public is that the

/// [resource_handler!] macro requires this function.

///

/// # Safety

/// The provided pointers must all be valid and point to the appropriate data structures.

#[inline]

#[doc(hidden)]

        },

    }

/// Trait with functions relating to [CoapResource]s with an unknown data type.

pub trait UntypedCoapResource: Any + Debug {

    /// Returns the uri_path this resource responds to.

    fn uri_path(&self) -> &str;

    /// Provides a reference to this resource as an [Any] trait object.

    ///

    /// You can use the resulting [Any] reference to downcast the resource to its appropriate

    /// concrete type (if you wish to e.g. change the application data).

    ///

    /// If you use unstable Rust, you can use trait upcasting instead (`[value] as Any`).

    fn as_any(&self) -> &dyn Any;

    /// Attempts to regain exclusive ownership of the inner resource in order to drop it.

    ///

    /// This function is used by the [CoapContext](crate::context::CoapContext) on cleanup to

    /// reclaim resources before dropping the context itself. *You should not use this function*.

    ///

    /// # Panics

    /// Panics if the inner resource instance associated with this resource cannot be exclusively

    /// dropped, i.e. because the underlying [Rc] is used elsewhere.

    #[doc(hidden)]

    fn drop_inner_exclusive(self: Box<Self>);

    /// Returns the raw resource associated with this CoapResource.

    ///

    /// # Safety

    /// You must not do anything with this resource that could interfere with this instance.

    /// Most notably, you must not...

    /// - ...free the returned value using [coap_delete_resource](libcoap_sys::coap_delete_resource)

    /// - ...associate the raw resource with a CoAP context, because if the context is dropped, so

    ///   will the resource.

    /// - ...modify the application-specific data.

    unsafe fn raw_resource(&mut self) -> *mut coap_resource_t;

}

/// Representation of a CoapResource that can be requested from a server.

#[derive(Debug)]

pub struct CoapResource<D: Any + ?Sized + Debug> {

    inner: CoapFfiRcCell<CoapResourceInner<D>>,

}

/// Container for resource handlers for various CoAP methods.

#[derive(Debug)]

struct CoapResourceHandlers<D: Any + ?Sized + Debug> {

    get: Option<CoapRequestHandler<D>>,

    put: Option<CoapRequestHandler<D>>,

    delete: Option<CoapRequestHandler<D>>,

    post: Option<CoapRequestHandler<D>>,

    fetch: Option<CoapRequestHandler<D>>,

    ipatch: Option<CoapRequestHandler<D>>,

    patch: Option<CoapRequestHandler<D>>,

}

impl<D: Any + ?Sized + Debug> Default for CoapResourceHandlers<D> {

}

impl<D: Any + ?Sized + Debug> CoapResourceHandlers<D> {

    #[inline]

        }

    #[inline]

    // Clippy complains about this being unused, but I'd like to keep it for consistency.

    #[allow(unused)]

        }

    // Kept for consistency

    #[allow(unused)]

    #[inline]

        }

    #[inline]

        }

}

/// Inner part of a [CoapResource], which is referenced inside the raw resource and might be

/// referenced multiple times, e.g. outside and inside of a resource handler.

#[derive(Debug)]

pub(crate) struct CoapResourceInner<D: Any + ?Sized + Debug> {

    raw_resource: *mut coap_resource_t,

    user_data: Box<D>,

    handlers: CoapResourceHandlers<D>,

}

impl<D: Any + ?Sized + Debug> CoapResource<D> {

    /// Creates a new CoapResource for the given `uri_path`.

    ///

    /// Handlers that are associated with this resource have to be able to take a reference to the

    /// provided `user_data` value as their first value.

    ///

    /// The `notify_con` parameter specifies whether observe notifications originating from this

    /// resource are sent as confirmable or non-confirmable.

                    } else {

                    }) as i32,

            );

    /// Notify any observers about changes to this resource.

    /// Sets whether this resource can be observed by clients according to

    /// [RFC 7641](https://datatracker.ietf.org/doc/html/rfc7641).

    /// Sets whether observe notifications for this resource should be sent as confirmable or

    /// non-confirmable CoAP messages.

    /// Returns the user data associated with this resource.

    /// Mutably returns the user data associated with this resource.

    /// Restores a resource from its raw [coap_resource_t](libcoap_sys::coap_resource_t).

    ///

    /// # Safety

    /// The supplied pointer must point to a valid [coap_resource_t](libcoap_sys::coap_resource_t)

    /// instance that has a `Rc<RefCell<CoapResourceInner<D>>>` as its user data.

    /// Sets the handler function for a given method code.

    /// Adds an attribute with a name and an optional value to a CoAP resource object.

            };

            // coap_new_str_const allocates memory, which should be freed when

            // the resource is deleted. Freeing a null pointer is a no-op here

            _ => {

            },

        };

        // Take handler function out of resource handler so that we no longer need the inner borrow

        // (otherwise, we couldn't call any resource functions in the handler).

}

impl<D: Any + ?Sized + Debug> UntypedCoapResource for CoapResource<D> {

}

#[doc(hidden)]

impl<D: Any + ?Sized + Debug> From<CoapFfiRcCell<CoapResourceInner<D>>> for CoapResource<D> {

}

impl<D: Any + ?Sized + Debug> Drop for CoapResourceInner<D> {

}

/// A handler for CoAP requests on a resource.

///

/// This handler can be associated with a [CoapResource] in order to be called when a request for

/// the associated resource and the provided method arrives. The handler is then able to generate

/// and send a response to the request accordingly.

///

/// # Creating a CoapRequestHandler

/// There are multiple ways to create a [CoapRequestHandler]:

/// - Using the [resource_handler!] macro: Preferred for handlers with a static lifetime (i.e.,

///   function pointers, not closures).

/// - Using [CoapRequestHandler::new]: Preferred for closures if you don't need access to the

///   [CoapResource] itself (but can be used for function pointers as well).

/// - Using [CoapRequestHandler::new_resource_ref]: Preferred for closures if you need access to

///   the [CoapResource] itself (but can be used for function pointers as well).

///

/// For method 2, the provided handler has to be a `FnMut(&mut D, &mut CoapServerSession, &CoapRequest, CoapResponse)`,

/// while for the other two methods, the handler has to be a `FnMut(&CoapResource<D>, &mut CoapServerSession, &CoapRequest, CoapResponse)`,

/// with the following arguments:

/// - Either the associated [CoapResource] or the user data depending on the type of handler.

///   Getting the user data directly without the associated resource has the advantage that it is

///   easy to pass a method as a handler, while getting the [CoapResource] gives you the option to

///   manipulate the resource (you can still get the user data from the resource using

///   [CoapResource::user_data].

/// - The server-side session with the peer this request was received from. You may want to store or

///   retrieve additional information about the peer using [CoapSessionCommon::set_app_data()] and

///   [CoapSessionCommon::app_data()].

/// - The incoming [CoapRequest] received from the client.

/// - A prepared [CoapResponse] instance that is already set to the correct token value to be

///   treated as a response to the request by the client.

// We'll allow the complex type as trait aliases are experimental and we'll probably want to use

// those instead of aliasing the entire type including wrappers.

#[allow(clippy::type_complexity)]

pub struct CoapRequestHandler<D: Any + ?Sized + Debug> {

    raw_handler: unsafe extern "C" fn(

        resource: *mut coap_resource_t,

        session: *mut coap_session_t,

        incoming_pdu: *const coap_pdu_t,

        query: *const coap_string_t,

        response_pdu: *mut coap_pdu_t,

    ),

    dynamic_handler_function:

        Option<Box<dyn FnMut(&CoapResource<D>, &mut CoapServerSession, &CoapRequest, CoapResponse)>>,

    __handler_data_type: PhantomData<D>,

}

impl<D: 'static + ?Sized + Debug> CoapRequestHandler<D> {

    /// Creates a new CoapResourceHandler with the given function as the handler function to call.

    /// Creates a new CoapResourceHandler with the given function as the handler function to call.

    ///

    /// In contrast to [CoapRequestHandler::new], the handler for this function is not provided with

    /// a direct reference to the user data, but instead with a reference to the associated

    /// `CoapResource`. This way, you can perform actions on the resource directly (e.g., notify

    /// observers).

    /// Creates a new request handler using the given raw handler function.

    ///

    /// The handler function provided here is called directly by libcoap.

    ///

    /// # Safety

    /// The handler function must not modify the user data value inside of the provided raw resource

    /// in a way that would break normal handler functions. Also, neither the resource nor the

    /// session may be freed by calling `coap_delete_resource` or `coap_session_release`.

    // We'll allow the complex type as trait aliases are experimental and we'll probably want to use

    // those instead of aliasing the entire type including wrappers.

    #[allow(clippy::type_complexity)]

}

impl<D: 'static + ?Sized + Debug> Debug for CoapRequestHandler<D> {

}