Plugins docs (#11)

Author: levkk

docs/configuration/pgdog.toml/plugins.md

@@ -1,11 +1,6 @@
 # Plugin settings
 
-!!! warning
-    Plugins are not currently supported anymore. We will pick them up again if there is more interest
-    from the community.
-
-[Plugins](../../features/plugins/index.md) are dynamically loaded at pooler startup. These settings control which plugins are loaded. In the future, more
-options will be available to configure plugin behavior.
+[Plugins](../../features/plugins/index.md) are dynamically loaded at PgDog startup. These settings control which plugins are loaded.
 
 Plugins are a TOML list, so for each plugin you want to enable, add a `[[plugins]]` entry to `pgdog.toml`. For example:
 
@@ -24,4 +19,12 @@ name = "alice_router"
 ### **`name`**
 
 Name of the plugin to load. This is used by PgDog to look up the shared library object in [`LD_LIBRARY_PATH`](https://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html). For example, if your plugin
-name is `router`, PgDog will look for `librouter.so` on Linux, `librouter.dll` on Windows and `librouter.dylib` on Mac OS.
+name is `router`, PgDog will look for `librouter.so` on Linux, `librouter.dll` on Windows, and `librouter.dylib` on Mac OS.
+
+Additionally, you can pass the relative or absolute path to the shared library itself:
+
+```toml
+name = "/opt/plugins/librouter.so"
+```
+
+Make sure the user running PgDog has read & execute permissions on the library.

docs/features/plugins/.pages

@@ -1,4 +1,2 @@
 nav:
-  - 'index.md'
-  - 'rust.md'
   - '...'

docs/features/plugins/c.md

@@ -1,94 +1,178 @@
 # Plugins overview
 
-!!! warning
-    Plugins are currently disabled. The C FFI interface is too awkward to pass all the required
-    context to the query router.
+PgDog comes with a powerful plugin system that allows you to customize the query routing behavior. Plugins are written in Rust, compiled into shared libraries, and loaded at runtime.
 
-One of features that make PgDog particularly powerful is its plugin system. Users of PgDog can write plugins
-in any language and inject them inside the query router to direct query traffic, to rewrite queries, or to block
-them entirely and return custom results.
 
-## API
+## Getting started
 
-PgDog plugins are shared libraries loaded at application startup. They can be written in any programming language, as long
-as that language can be compiled to a shared library, and can expose a predefined set of C ABI-compatible functions.
+PgDog plugins are Rust libraries. To create a plugin, first create a project with Cargo:
 
-### Functions
+```
+cargo init --lib my_plugin
+```
 
-#### `pgdog_init`
+#### Dependencies
 
-This function is executed once when PgDog loads the plugin, at application startup. It allows to initialize any
-kind of internal plugin state. Execution of this function is synchronized, so it's safe to execute any thread-unsafe
+Inside your project's `Cargo.toml`, add the following settings and dependencies:
+
+```toml
+[lib]
+crate-type = ["rlib", "cdylib"]
+
+[dependencies]
+pgdog-plugin = "0.1.6"
+```
+
+This turns the crate into a shared library, exposing its functions using the C ABI, which PgDog will call at runtime.
+
+!!! note
+    The `pgdog-plugin` crate is published on [crates.io](https://crates.io/crates/pgdog-plugin) and is fully documented. You can find our [Rust docs here](https://docsrs.pgdog.dev), including all dependencies like [`pg_query`](https://docsrs.pgdog.dev/pg_query/index.html).
+
+### Writing plugins
+
+When writing plugins, it's helpful to import most commonly used macros, functions and types. You can do so with just one line of code:
+
+```rust
+use pgdog_plugin::prelude::*;
+```
+
+PgDog plugins have a list of required methods they need to expose. They are called by PgDog at plugin startup and validate that it
+was correctly written.
+
+You don't need to implement them yourself. Add the following to your plugin's `src/lib.rs` file:
+
+```rust
+macros::plugin!();
+```
+
+These ensure the following requirements are followed:
+
+1. The plugin is compiled with the same version of the Rust compiler as PgDog itself
+2. They are using the same version of `pg_query`
+
+See [Safety](#safety) section for more info.
+
+
+## Functions
+
+### `init`
+
+This function is executed once at startup, when PgDog loads the plugin. It allows to initialize any
+kind of internal plugin state. Execution of this function is synchronized, so it's safe to include any thread-unsafe
 functions or initialize synchronization primitives, like mutexes.
 
 
 This function has the following signature:
 
-=== "Rust"
-    ```rust
-    pub extern "C" fn pgdog_init() {}
-    ```
-=== "C/C++"
-    ```c
-    void pgdog_init();
-    ```
+```rust
+#[init]
+fn init() {
+    // Perform any initialization routines here.
+}
+```
 
 
-#### `pgdog_route_query`
+### `route`
 
-This function is called every time the query router sees a new query and needs to figure out
-where this query should be sent. The query text and parameters will be provided and the router
-expects the plugin to parse the query and provide a route.
+This function is called every time the query router processes a query and needs to figure out
+where this query should be sent.
 
 This function has the following signature:
 
-=== "Rust"
-    ```rust
-    use pgdog_plugin::*;
+```rust
+#[route]
+fn route(context: Context) -> Route {
+    Route::unknown()
+}
+```
+
+#### Inputs
+
+The [`Context`](https://docsrs.pgdog.dev/pgdog_plugin/context/struct.Context.html) struct provides the following information:
+
+- Number of shards in the database cluster
+- Does the cluster have replicas
+- The Abstract Syntax Tree (AST) of the statement, parsed by `pg_query`
 
-    pub extern "C" fn pgdog_route_query(Input query) -> Output {
-        Route::unknown()
-    }
-    ```
-=== "C/C++"
-    ```c
-    Output pgdog_route_query(Input query);
-    ```
 
+#### Outputs
 
-##### Data structures
+The plugin is expected to return a [`Route`](https://docsrs.pgdog.dev/pgdog_plugin/context/struct.Route.html). It can pass the following information back to PgDog:
 
-This function expects an input of type `Input` and must return a struct of type `Output`. The input contains
-the query PgDog received and the current database configuration, e.g. number of shards, replicas, and if there
-is a primary database that can serve writes.
+- Which shard(s) to send the query to
+- Is the query a read or a write, sending it to a replica or the primary, respectively
 
-The output structure contains the routing decision (e.g. query should go to a replica) and any additional information that the plugin wants to communicate, which depends on the routing decision. For example,
-if the plugin wants PgDog to intercept this query and return a custom result, rows of that result will be
-included in the output.
+Both of these are optional. If you don't return either one, the plugin doesn't influence the routing decision at all and can be used for logging queries, or some other purpose.
 
 
-#### `pgdog_fini`
 
-This function is called before the pooler is shut down. This allows plugins to perform any tasks, like saving
+### `fini`
+
+This function is called before PgDog is shut down. It allows plugins to perform any cleanup tasks, like saving
 some internal state to a durable medium.
 
 This function has the following signature:
 
-=== "Rust"
-    ```rust
-    pub extern "C" fn pgdog_fini() {}
-    ```
-=== "C/C++"
-    ```c
-    void pgdog_fini();
-    ```
+```rust
+#[fini]
+fn fini() {
+    // Any cleanup routines go here.
+}
+```
+
+## Loading plugins
+
+Plugins need to be compiled and placed into a folder on your machine where PgDog can find them. This can be achieved using several approaches:
+
+1. Place the shared library into a standard operating system folder, e.g.: `/usr/lib` or `/lib`
+2. Export the plugin's parent directory into the `LD_LIBRARY_PATH` environment variable, provided to PgDog at runtime
+3. Pass the absolute (or relative) path to the plugin in [`pgdog.toml`](../../configuration/pgdog.toml/plugins.md)
+
+!!! note
+    Make sure to compile plugins in release mode for good performance: `cargo build --release`. The plugin's shared library will be in `target/release` folder of your Cargo project, e.g., `target/release/libmy_plugin.so`.
+
+You then need to specify which plugins you'd like PgDog to load at runtime:
+
+```toml
+[[plugins]]
+name = "my_plugin"
+```
+
+This can be the name of the library (without the `lib` prefix or the `.so`/`.dylib` extension) or relative/absolute path to the shared library, for example:
+
+```toml
+[[plugins]]
+name = "/usr/lib/libmy_plugin.so"
+```
 
 ## Examples
 
-Example plugins written in Rust and C are
-included in [GitHub](https://github.com/levkk/pgdog/tree/main/examples).
+Example plugins written in Rust are in [GitHub](https://github.com/pgdogdev/pgdog/tree/main/plugins).
+
+## Safety
+
+Rust plugins can do anything. There is no virtualization layer or checks on their behavior. With great power comes great responsibility, so make sure the plugins you use are trusted (and tested).
+
+This is intentional. We don't want to limit what you can do inside plugins nor are we there to tell you what you shouldn't be doing. It's your data stack, and you're the owner.
+
+An additional benefit of using Rust is: plugins are very fast! If written correctly, they will have minimal to no latency impact of your database.
+
+### Rust/C ABI
+
+Unlike C, the Rust language doesn't have a stable ABI. Therefore, additional care needs to be taken when loading and executing routines from shared libraries. This is enforced automatically by `pgdog-plugin`, but you should still be aware of them.
+
+#### Rust compiler version
+
+Whatever Rust compiler version is used to build PgDog itself needs to be used to build the plugins. This is checked at runtime and plugins that don't follow this requirement are **not loaded**.
+
+#### `pg_query` version
+
+Since we're passing the AST itself down to the plugins, we need to make sure that the versions of the `pg_query` library used by PgDog and the plugin are the same. This is done automatically if you're using the primitives exported by the `pgdog-plugin` crate:
 
-## Learn more
+```rust
+// Manually use the exported primitives.
+use pgdog_plugin::pg_query;
 
-- [Plugins in Rust](rust.md)
-- [Plugins in C](c.md)
+// Automatically import them.
+use pgdog_plugin::prelude::*;
+```