Trait ApiSet 

pub trait ApiSet {
    // Required methods
    fn namespace(&self) -> &str;
    fn exec_function(
        &mut self,
        name: &str,
        version: i32,
        args: Document,
        request_cookie: Option<RequestCookie>,
    ) -> Option<Result<Option<Bson>, ErrorCode>>;

    // Provided methods
    fn update(&mut self) { ... }
    fn next_result(
        &mut self,
    ) -> Option<(RequestCookie, Result<Option<Bson>, ErrorCode>)> { ... }
}

The ApiSet trait represents a set of APIs that can be remotely invoked by a connecting Honk-RPC client.

Example

This exampe ApiSet implements two methods, example::println() and example::async_println(). The println() method immediatley prints, whereas async_println() queues request and prints the messagge at a later date via update()

const RUNTIME_ERROR_INVALID_ARG: ErrorCode = ErrorCode::Runtime(1i32);

struct PrintlnApiSet {
    // queued print reuests
    async_println_work: Vec<(Option<RequestCookie>, String)>,
    // successful async requests
    async_println_cookies: VecDeque<RequestCookie>,
}

impl PrintlnApiSet {
  // prints message immediately
  fn println_0(
      &mut self,
      mut args: bson::document::Document,
  ) -> Option<Result<Option<bson::Bson>, ErrorCode>> {
    if let Some(bson::Bson::String(val)) = args.get_mut("val") {
        println!("example::echo_0(val): '{}'", val);
        Some(Ok(Some(bson::Bson::String(std::mem::take(val)))))
    } else {
        Some(Err(RUNTIME_ERROR_INVALID_ARG))
    }
  }

  // queues message up for printing later
  fn async_println_0(
      &mut self,
      request_cookie: Option<RequestCookie>,
      mut args: bson::document::Document,
  ) -> Option<Result<Option<bson::Bson>, ErrorCode>>{
    if let Some(bson::Bson::String(val)) = args.get_mut("val") {
        self.async_println_work.push((request_cookie, std::mem::take(val)));
        None
    } else {
        Some(Err(RUNTIME_ERROR_INVALID_ARG))
    }
  }
}

impl ApiSet for PrintlnApiSet {
    fn namespace(&self) -> &str {
        "example"
    }

    // handles and routes requests for `println` and `async_println`
    fn exec_function(
        &mut self,
        name: &str,
        version: i32,
        args: bson::document::Document,
        request_cookie: Option<RequestCookie>,
    ) -> Option<Result<Option<bson::Bson>, ErrorCode>> {
        match (name, version) {
            ("println", 0) => self.println_0(args),
            ("async_println", 0) => self.async_println_0(request_cookie, args),
            (name, version) => {
                println!("received {{ name: '{}', version: {} }}", name, version);
                Some(Err(ErrorCode::RequestFunctionInvalid))
            }
        }
    }

    // handles queued `async_println` requests
    fn update(&mut self) {
        for ((cookie, val)) in self.async_println_work.drain(..) {
            println!("{}", val);
            if let Some(cookie) = cookie {
                self.async_println_cookies.push_back(cookie);
            }
        }
    }

    // finally return queued async results
    fn next_result(&mut self) -> Option<(RequestCookie, Result<Option<bson::Bson>, ErrorCode>)> {
        if let Some(cookie) = self.async_println_cookies.pop_front() {
            Some((cookie, Ok(None)))
        } else {
            None
        }
    }
}

Required Methods

fn namespace(&self) -> &str

Returns the namespace of this ApiSet.

fn exec_function( &mut self, name: &str, version: i32, args: Document, request_cookie: Option<RequestCookie>, ) -> Option<Result<Option<Bson>, ErrorCode>>

Schedules the execution of the requested remote procedure call. Calls to this function map directly to a received Honk-RPC request. Each request has the following parameters:

• name: The name of the function to execute.
• version: The version of the function to execute.
• args: The arguments to pass to the function.
• request_cookie: An optional cookie to track the request.

This function handles both synchronous and asynchronous requests. The possible return values for each are:

• Synchronous requests may execute and signal success by returning Some(Ok(..)).
• Synchronous requests may execute and signal failure by returning Some(Err(..)).
• Asynchronous requests must defer execution by returning None.

Provided Methods

fn update(&mut self)

Updates any internal state required to make forward progress on any requested remote procedure calls. Implementation of this method is optional and not needed if the implementor does not have any async functions. If left unimplemented, this function is a no-op.

fn next_result( &mut self, ) -> Option<(RequestCookie, Result<Option<Bson>, ErrorCode>)>

Returns the result of any in-flight asynchronous requests.

• Asynchronous requests may signal success by returning Some((cookie, Ok(..)))
• Asynchronous requests may signal failure by returning Some((cookie, Err(..)))
• returns None if no asynchronous results are available

This method is optional and not needed if the implementor does not have any async functions, in which case the default implementation will return None.

Implementors