From bf36ef7fd9fc0da93610decd166b196ac2d5a2c8 Mon Sep 17 00:00:00 2001 From: nathan Date: Thu, 1 Dec 2022 10:59:22 +0800 Subject: [PATCH] chore: update documentation --- frontend/rust-lib/dart-ffi/src/lib.rs | 4 +-- .../dart-ffi/src/model/ffi_response.rs | 6 ++-- frontend/rust-lib/flowy-error/src/errors.rs | 4 +-- .../rust-lib/flowy-test/src/event_builder.rs | 6 ++-- frontend/rust-lib/lib-dispatch/src/data.rs | 4 +-- .../rust-lib/lib-dispatch/src/dispatcher.rs | 14 ++++---- .../lib-dispatch/src/errors/errors.rs | 8 ++--- .../lib-dispatch/src/module/module.rs | 34 ++++++++++++++----- .../lib-dispatch/src/response/builder.rs | 6 ++-- .../lib-dispatch/src/response/responder.rs | 8 ++--- .../lib-dispatch/src/response/response.rs | 12 +++---- .../lib-dispatch/src/service/handler.rs | 5 +-- .../lib-dispatch/src/service/service.rs | 18 +++++----- 13 files changed, 74 insertions(+), 55 deletions(-) diff --git a/frontend/rust-lib/dart-ffi/src/lib.rs b/frontend/rust-lib/dart-ffi/src/lib.rs index 8165cbf6c3..78ddb3dfd8 100644 --- a/frontend/rust-lib/dart-ffi/src/lib.rs +++ b/frontend/rust-lib/dart-ffi/src/lib.rs @@ -46,7 +46,7 @@ pub extern "C" fn async_event(port: i64, input: *const u8, len: usize) { } Some(e) => e.event_dispatcher.clone(), }; - let _ = AFPluginDispatcher::async_send_with_callback(dispatcher, request, move |resp: EventResponse| { + let _ = AFPluginDispatcher::async_send_with_callback(dispatcher, request, move |resp: AFPluginEventResponse| { log::trace!("[FFI]: Post data to dart through {} port", port); Box::pin(post_to_flutter(resp, port)) }); @@ -83,7 +83,7 @@ pub extern "C" fn set_stream_port(port: i64) -> i32 { pub extern "C" fn link_me_please() {} #[inline(always)] -async fn post_to_flutter(response: EventResponse, port: i64) { +async fn post_to_flutter(response: AFPluginEventResponse, port: i64) { let isolate = allo_isolate::Isolate::new(port); match isolate .catch_unwind(async { diff --git a/frontend/rust-lib/dart-ffi/src/model/ffi_response.rs b/frontend/rust-lib/dart-ffi/src/model/ffi_response.rs index ea9afa5720..c34252b0d0 100644 --- a/frontend/rust-lib/dart-ffi/src/model/ffi_response.rs +++ b/frontend/rust-lib/dart-ffi/src/model/ffi_response.rs @@ -1,5 +1,5 @@ use flowy_derive::{ProtoBuf, ProtoBuf_Enum}; -use lib_dispatch::prelude::{EventResponse, Payload, StatusCode}; +use lib_dispatch::prelude::{AFPluginEventResponse, Payload, StatusCode}; #[derive(ProtoBuf_Enum, Clone, Copy)] pub enum FFIStatusCode { @@ -23,8 +23,8 @@ pub struct FFIResponse { code: FFIStatusCode, } -impl std::convert::From for FFIResponse { - fn from(resp: EventResponse) -> Self { +impl std::convert::From for FFIResponse { + fn from(resp: AFPluginEventResponse) -> Self { let payload = match resp.payload { Payload::Bytes(bytes) => bytes.to_vec(), Payload::None => vec![], diff --git a/frontend/rust-lib/flowy-error/src/errors.rs b/frontend/rust-lib/flowy-error/src/errors.rs index 8b32005378..36e689ab14 100644 --- a/frontend/rust-lib/flowy-error/src/errors.rs +++ b/frontend/rust-lib/flowy-error/src/errors.rs @@ -1,7 +1,7 @@ use bytes::Bytes; use flowy_derive::ProtoBuf; use flowy_error_code::ErrorCode; -use lib_dispatch::prelude::{EventResponse, ResponseBuilder}; +use lib_dispatch::prelude::{AFPluginEventResponse, ResponseBuilder}; use std::{convert::TryInto, fmt, fmt::Debug}; pub type FlowyResult = std::result::Result; @@ -93,7 +93,7 @@ impl fmt::Display for FlowyError { } impl lib_dispatch::Error for FlowyError { - fn as_response(&self) -> EventResponse { + fn as_response(&self) -> AFPluginEventResponse { let bytes: Bytes = self.clone().try_into().unwrap(); println!("Serialize FlowyError: {:?} to event response", self); diff --git a/frontend/rust-lib/flowy-test/src/event_builder.rs b/frontend/rust-lib/flowy-test/src/event_builder.rs index 8d34aa7acd..f86e733a7e 100644 --- a/frontend/rust-lib/flowy-test/src/event_builder.rs +++ b/frontend/rust-lib/flowy-test/src/event_builder.rs @@ -1,7 +1,7 @@ use crate::FlowySDKTest; use flowy_user::{entities::UserProfilePB, errors::FlowyError}; use lib_dispatch::prelude::{ - AFPluginDispatcher, AFPluginFromBytes, AFPluginRequest, EventResponse, StatusCode, ToBytes, *, + AFPluginDispatcher, AFPluginEventResponse, AFPluginFromBytes, AFPluginRequest, StatusCode, ToBytes, *, }; use std::{ convert::TryFrom, @@ -124,7 +124,7 @@ where self.context.sdk.dispatcher() } - fn get_response(&self) -> EventResponse { + fn get_response(&self) -> AFPluginEventResponse { self.context .response .as_ref() @@ -141,7 +141,7 @@ where pub struct TestContext { pub sdk: FlowySDKTest, request: Option, - response: Option, + response: Option, } impl TestContext { diff --git a/frontend/rust-lib/lib-dispatch/src/data.rs b/frontend/rust-lib/lib-dispatch/src/data.rs index 901529c05c..8f37383934 100644 --- a/frontend/rust-lib/lib-dispatch/src/data.rs +++ b/frontend/rust-lib/lib-dispatch/src/data.rs @@ -2,7 +2,7 @@ use crate::{ byte_trait::*, errors::{DispatchError, InternalError}, request::{unexpected_none_payload, AFPluginEventRequest, FromAFPluginRequest, Payload}, - response::{AFPluginResponder, EventResponse, ResponseBuilder}, + response::{AFPluginEventResponse, AFPluginResponder, ResponseBuilder}, util::ready::{ready, Ready}, }; use bytes::Bytes; @@ -53,7 +53,7 @@ impl AFPluginResponder for AFPluginData where T: ToBytes, { - fn respond_to(self, _request: &AFPluginEventRequest) -> EventResponse { + fn respond_to(self, _request: &AFPluginEventRequest) -> AFPluginEventResponse { match self.into_inner().into_bytes() { Ok(bytes) => { log::trace!("Serialize Data: {:?} to event response", std::any::type_name::()); diff --git a/frontend/rust-lib/lib-dispatch/src/dispatcher.rs b/frontend/rust-lib/lib-dispatch/src/dispatcher.rs index a90e10d744..dc5defd0f8 100644 --- a/frontend/rust-lib/lib-dispatch/src/dispatcher.rs +++ b/frontend/rust-lib/lib-dispatch/src/dispatcher.rs @@ -2,7 +2,7 @@ use crate::runtime::AFPluginRuntime; use crate::{ errors::{DispatchError, Error, InternalError}, module::{as_plugin_map, AFPlugin, AFPluginMap, AFPluginRequest}, - response::EventResponse, + response::AFPluginEventResponse, service::{AFPluginServiceFactory, Service}, }; use derivative::*; @@ -30,7 +30,7 @@ impl AFPluginDispatcher { } } - pub fn async_send(dispatch: Arc, request: Req) -> DispatchFuture + pub fn async_send(dispatch: Arc, request: Req) -> DispatchFuture where Req: std::convert::Into, { @@ -41,10 +41,10 @@ impl AFPluginDispatcher { dispatch: Arc, request: Req, callback: Callback, - ) -> DispatchFuture + ) -> DispatchFuture where Req: std::convert::Into, - Callback: FnOnce(EventResponse) -> BoxFuture<'static, ()> + 'static + Send + Sync, + Callback: FnOnce(AFPluginEventResponse) -> BoxFuture<'static, ()> + 'static + Send + Sync, { let request: AFPluginRequest = request.into(); let plugins = dispatch.plugins.clone(); @@ -73,7 +73,7 @@ impl AFPluginDispatcher { } } - pub fn sync_send(dispatch: Arc, request: AFPluginRequest) -> EventResponse { + pub fn sync_send(dispatch: Arc, request: AFPluginRequest) -> AFPluginEventResponse { futures::executor::block_on(async { AFPluginDispatcher::async_send_with_callback(dispatch, request, |_| Box::pin(async {})).await }) @@ -105,7 +105,7 @@ where } } -pub type BoxFutureCallback = Box BoxFuture<'static, ()> + 'static + Send + Sync>; +pub type BoxFutureCallback = Box BoxFuture<'static, ()> + 'static + Send + Sync>; #[derive(Derivative)] #[derivative(Debug)] @@ -127,7 +127,7 @@ pub(crate) struct DispatchService { } impl Service for DispatchService { - type Response = EventResponse; + type Response = AFPluginEventResponse; type Error = DispatchError; type Future = BoxFuture<'static, Result>; diff --git a/frontend/rust-lib/lib-dispatch/src/errors/errors.rs b/frontend/rust-lib/lib-dispatch/src/errors/errors.rs index 5d43a4b496..4e2787622e 100644 --- a/frontend/rust-lib/lib-dispatch/src/errors/errors.rs +++ b/frontend/rust-lib/lib-dispatch/src/errors/errors.rs @@ -1,7 +1,7 @@ use crate::{ byte_trait::AFPluginFromBytes, request::AFPluginEventRequest, - response::{EventResponse, ResponseBuilder}, + response::{AFPluginEventResponse, ResponseBuilder}, }; use bytes::Bytes; use dyn_clone::DynClone; @@ -10,7 +10,7 @@ use std::fmt; use tokio::{sync::mpsc::error::SendError, task::JoinError}; pub trait Error: fmt::Debug + DynClone + Send + Sync { - fn as_response(&self) -> EventResponse; + fn as_response(&self) -> AFPluginEventResponse; } dyn_clone::clone_trait_object!(Error); @@ -80,7 +80,7 @@ impl AFPluginFromBytes for DispatchError { } } -impl From for EventResponse { +impl From for AFPluginEventResponse { fn from(err: DispatchError) -> Self { err.inner_error().as_response() } @@ -121,7 +121,7 @@ impl fmt::Display for InternalError { } impl Error for InternalError { - fn as_response(&self) -> EventResponse { + fn as_response(&self) -> AFPluginEventResponse { let error = format!("{}", self).into_bytes(); ResponseBuilder::Internal().data(error).build() } diff --git a/frontend/rust-lib/lib-dispatch/src/module/module.rs b/frontend/rust-lib/lib-dispatch/src/module/module.rs index f560501397..e091a6f4e1 100644 --- a/frontend/rust-lib/lib-dispatch/src/module/module.rs +++ b/frontend/rust-lib/lib-dispatch/src/module/module.rs @@ -2,7 +2,7 @@ use crate::{ errors::{DispatchError, InternalError}, module::{container::AFPluginStateMap, AFPluginState}, request::{payload::Payload, AFPluginEventRequest, FromAFPluginRequest}, - response::{AFPluginResponder, EventResponse}, + response::{AFPluginEventResponse, AFPluginResponder}, service::{ factory, AFPluginHandler, AFPluginHandlerService, AFPluginServiceFactory, BoxService, BoxServiceFactory, Service, ServiceRequest, ServiceResponse, @@ -45,9 +45,21 @@ impl std::convert::From for AFPluginE } } +/// A plugin is used to handle the events that the plugin can handle. +/// +/// When an event is a dispatched by the `AFPluginDispatcher`, the dispatcher will +/// find the corresponding plugin to handle the event. The name of the event must be unique, +/// which means only one handler will get called. +/// pub struct AFPlugin { pub name: String, + + /// a list of `AFPluginState` that the plugin registers. The state can be read by the plugin's handler. states: Arc, + + /// Contains a list of factories that are used to generate the services used to handle the passed-in + /// `ServiceRequest`. + /// event_service_factory: Arc>>, } @@ -89,12 +101,12 @@ impl AFPlugin { { let event: AFPluginEvent = event.into(); if self.event_service_factory.contains_key(&event) { - log::error!("Duplicate Event: {:?}", &event); + panic!("Register duplicate Event: {:?}", &event); + } else { + Arc::get_mut(&mut self.event_service_factory) + .unwrap() + .insert(event, factory(AFPluginHandlerService::new(handler))); } - - Arc::get_mut(&mut self.event_service_factory) - .unwrap() - .insert(event, factory(AFPluginHandlerService::new(handler))); self } @@ -103,6 +115,10 @@ impl AFPlugin { } } +/// A request that will be passed to the corresponding plugin. +/// +/// Each request can carry the payload that will be deserialized into the corresponding data struct. +/// #[derive(Debug, Clone)] pub struct AFPluginRequest { pub id: String, @@ -138,7 +154,7 @@ impl std::fmt::Display for AFPluginRequest { } impl AFPluginServiceFactory for AFPlugin { - type Response = EventResponse; + type Response = AFPluginEventResponse; type Error = DispatchError; type Service = BoxService; type Context = (); @@ -160,7 +176,7 @@ pub struct AFPluginService { } impl Service for AFPluginService { - type Response = EventResponse; + type Response = AFPluginEventResponse; type Error = DispatchError; type Future = BoxFuture<'static, Result>; @@ -196,7 +212,7 @@ pub struct AFPluginServiceFuture { } impl Future for AFPluginServiceFuture { - type Output = Result; + type Output = Result; fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { let (_, response) = ready!(self.as_mut().project().fut.poll(cx))?.into_parts(); diff --git a/frontend/rust-lib/lib-dispatch/src/response/builder.rs b/frontend/rust-lib/lib-dispatch/src/response/builder.rs index a9d4ea6802..e20e648fd8 100644 --- a/frontend/rust-lib/lib-dispatch/src/response/builder.rs +++ b/frontend/rust-lib/lib-dispatch/src/response/builder.rs @@ -1,6 +1,6 @@ use crate::{ request::Payload, - response::{EventResponse, StatusCode}, + response::{AFPluginEventResponse, StatusCode}, }; macro_rules! static_response { @@ -30,8 +30,8 @@ impl ResponseBuilder { self } - pub fn build(self) -> EventResponse { - EventResponse { + pub fn build(self) -> AFPluginEventResponse { + AFPluginEventResponse { payload: self.payload, status_code: self.status, } diff --git a/frontend/rust-lib/lib-dispatch/src/response/responder.rs b/frontend/rust-lib/lib-dispatch/src/response/responder.rs index efd1c5ede1..0b25d1f2b9 100644 --- a/frontend/rust-lib/lib-dispatch/src/response/responder.rs +++ b/frontend/rust-lib/lib-dispatch/src/response/responder.rs @@ -2,18 +2,18 @@ use crate::errors::{DispatchError, InternalError}; use crate::{ request::AFPluginEventRequest, - response::{EventResponse, ResponseBuilder}, + response::{AFPluginEventResponse, ResponseBuilder}, }; use bytes::Bytes; pub trait AFPluginResponder { - fn respond_to(self, req: &AFPluginEventRequest) -> EventResponse; + fn respond_to(self, req: &AFPluginEventRequest) -> AFPluginEventResponse; } macro_rules! impl_responder { ($res: ty) => { impl AFPluginResponder for $res { - fn respond_to(self, _: &AFPluginEventRequest) -> EventResponse { + fn respond_to(self, _: &AFPluginEventRequest) -> AFPluginEventResponse { ResponseBuilder::Ok().data(self).build() } } @@ -32,7 +32,7 @@ where T: AFPluginResponder, E: Into, { - fn respond_to(self, request: &AFPluginEventRequest) -> EventResponse { + fn respond_to(self, request: &AFPluginEventRequest) -> AFPluginEventResponse { match self { Ok(val) => val.respond_to(request), Err(e) => e.into().into(), diff --git a/frontend/rust-lib/lib-dispatch/src/response/response.rs b/frontend/rust-lib/lib-dispatch/src/response/response.rs index 69abb82f8f..515ed95ba4 100644 --- a/frontend/rust-lib/lib-dispatch/src/response/response.rs +++ b/frontend/rust-lib/lib-dispatch/src/response/response.rs @@ -19,15 +19,15 @@ pub enum StatusCode { // serde user guide: https://serde.rs/field-attrs.html #[derive(Debug, Clone, Derivative)] #[cfg_attr(feature = "use_serde", derive(serde::Serialize))] -pub struct EventResponse { +pub struct AFPluginEventResponse { #[derivative(Debug = "ignore")] pub payload: Payload, pub status_code: StatusCode, } -impl EventResponse { +impl AFPluginEventResponse { pub fn new(status_code: StatusCode) -> Self { - EventResponse { + AFPluginEventResponse { payload: Payload::None, status_code, } @@ -51,7 +51,7 @@ impl EventResponse { } } -impl std::fmt::Display for EventResponse { +impl std::fmt::Display for AFPluginEventResponse { fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { f.write_fmt(format_args!("Status_Code: {:?}", self.status_code))?; @@ -64,9 +64,9 @@ impl std::fmt::Display for EventResponse { } } -impl AFPluginResponder for EventResponse { +impl AFPluginResponder for AFPluginEventResponse { #[inline] - fn respond_to(self, _: &AFPluginEventRequest) -> EventResponse { + fn respond_to(self, _: &AFPluginEventRequest) -> AFPluginEventResponse { self } } diff --git a/frontend/rust-lib/lib-dispatch/src/service/handler.rs b/frontend/rust-lib/lib-dispatch/src/service/handler.rs index 0f6a0ef9a5..52c9081983 100644 --- a/frontend/rust-lib/lib-dispatch/src/service/handler.rs +++ b/frontend/rust-lib/lib-dispatch/src/service/handler.rs @@ -11,11 +11,12 @@ use pin_project::pin_project; use crate::{ errors::DispatchError, request::{payload::Payload, AFPluginEventRequest, FromAFPluginRequest}, - response::{AFPluginResponder, EventResponse}, + response::{AFPluginEventResponse, AFPluginResponder}, service::{AFPluginServiceFactory, Service, ServiceRequest, ServiceResponse}, util::ready::*, }; +/// A closure that is run every time for the specified plugin event pub trait AFPluginHandler: Clone + 'static + Sync + Send where R: Future + Send + Sync, @@ -135,7 +136,7 @@ where Err(err) => { let req = req.take().unwrap(); let system_err: DispatchError = err.into(); - let res: EventResponse = system_err.into(); + let res: AFPluginEventResponse = system_err.into(); return Poll::Ready(Ok(ServiceResponse::new(req, res))); } }; diff --git a/frontend/rust-lib/lib-dispatch/src/service/service.rs b/frontend/rust-lib/lib-dispatch/src/service/service.rs index 3e0fbb819f..b1fed6e1aa 100644 --- a/frontend/rust-lib/lib-dispatch/src/service/service.rs +++ b/frontend/rust-lib/lib-dispatch/src/service/service.rs @@ -2,7 +2,7 @@ use std::future::Future; use crate::{ request::{payload::Payload, AFPluginEventRequest}, - response::EventResponse, + response::AFPluginEventResponse, }; pub trait Service { @@ -13,6 +13,8 @@ pub trait Service { fn call(&self, req: Request) -> Self::Future; } +/// Returns a future that can handle the request. For the moment, the request will be the +/// `AFPluginRequest` pub trait AFPluginServiceFactory { type Response; type Error; @@ -24,32 +26,32 @@ pub trait AFPluginServiceFactory { } pub(crate) struct ServiceRequest { - req: AFPluginEventRequest, + event_state: AFPluginEventRequest, payload: Payload, } impl ServiceRequest { - pub(crate) fn new(req: AFPluginEventRequest, payload: Payload) -> Self { - Self { req, payload } + pub(crate) fn new(event_state: AFPluginEventRequest, payload: Payload) -> Self { + Self { event_state, payload } } #[inline] pub(crate) fn into_parts(self) -> (AFPluginEventRequest, Payload) { - (self.req, self.payload) + (self.event_state, self.payload) } } pub struct ServiceResponse { request: AFPluginEventRequest, - response: EventResponse, + response: AFPluginEventResponse, } impl ServiceResponse { - pub fn new(request: AFPluginEventRequest, response: EventResponse) -> Self { + pub fn new(request: AFPluginEventRequest, response: AFPluginEventResponse) -> Self { ServiceResponse { request, response } } - pub fn into_parts(self) -> (AFPluginEventRequest, EventResponse) { + pub fn into_parts(self) -> (AFPluginEventRequest, AFPluginEventResponse) { (self.request, self.response) } }