CVPN-793: add plugin documentation with example plugin

docs/README.md

@@ -3,6 +3,7 @@
 * [Connection State Machine](connection_state_machine.md)
 * [UDP Session ID Rotation](udp_session_id.md)
 * [PMTU Discovery](pmtu_discovery.md)
+* [Plugin architecture](plugins.md)
 
 # Miscellaneous
 

docs/plugins.md

@@ -0,0 +1,79 @@
+# Plugins
+
+Plugins provides a way to control traffic flowing throught Lightway protocol.
+Applications can create a custom plugin and attach it to client or server.
+
+Plugins can be constructed by implementing the following trait (Ref: `lightway_core::Plugin`)
+
+```rust
+pub trait Plugin {
+    /// Hook to run during packet ingress
+    fn ingress(&self, data: &mut BytesMut) -> PluginResult;
+
+    /// Hook to run during packet egress
+    fn egress(&self, data: &mut BytesMut) -> PluginResult;
+}
+```
+
+
+The following is an example plugin to drop packets destined to a particular IP address.
+
+```rust
+use pnet::packet::ipv4::Ipv4Packet;
+use pnet::packet::tcp::TcpPacket;
+
+#[derive(Clone, Debug)]
+struct IpFilter(Ipv4Address);
+
+impl IpFilter {
+    pub fn new(ip: Ipv4Address) -> Self {
+        Self(ip)
+    }
+}
+
+impl Plugin for IpFilter {
+    fn ingress(&self, data: &mut BytesMut) -> PluginResult {
+        let mut packet = Ipv4Packet::new(pkt)?;
+        if packet.get_source() == self.0 {
+            PluginResult::Drop
+        } else {
+            PluginResult::Accept
+        }
+    }
+
+    fn egress(&self, data: &mut BytesMut) -> PluginResult {
+        let mut packet = Ipv4Packet::new(pkt)?;
+        if packet.get_source() == self.0 {
+            PluginResult::Drop
+        } else {
+            PluginResult::Accept
+        }
+    }
+}
+
+pub struct IpFilterPluginFactory {
+    filter: IpFilter,
+};
+
+impl IpFilterPluginFactory {
+    pub fn new(ip: Ipv4Address) -> Self {
+        let filter = IpFilter::new(ip);
+        Self { filter }
+    }
+}
+
+impl PluginFactory for IpFilterPluginFactory {
+    fn build(&self) -> Result<PluginType, PluginFactoryError> {
+        let filter = self.filter.clone();
+        Ok(Box::new(filter))
+    }
+}
+
+```
+
+Plugin factory's instance can be created and attached to a factory list `lightway_client::PluginFactoryList`
+
+And this plugin factory list can be applied to a client or server by sending it as an argument:
+`lightway_client::ClientConfig::inside_plugins` or `lightway_server:ServerConfig::inside_plugins`
+
+to `lightway_client::client` or `lightway_server::server` api to filter traffic.