Cursor Example

Author: system

Cargo.lock

@@ -18,6 +18,6 @@ members = [
     "examples/request-tracking",
     "examples/engine",
     "rwf-admin",
-    "examples/files", "examples/users", "examples/openapi", "examples/oidc", "examples/callbacks",
+    "examples/files", "examples/users", "examples/openapi", "examples/oidc", "examples/callbacks", "examples/cursor",
 ]
 exclude = ["examples/rails", "rwf-ruby", "examples/django", "rwf-fuzz"]

Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "cursor"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+rwf = {path = "../../rwf"}
+tokio = {version = "1.49.0", features = ["full"]}
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.149"

examples/cursor/Cargo.toml

@@ -0,0 +1,38 @@
+# Cursor
+Rwf has support for Cursors - with all advantages and disadvantages they come with.
+Every qualified (not data modifying) query can be used to create a Cursor.
+
+
+## Basics
+There are two base types of cursors. `ModelCursor` and `SelectiveCursor` the former is used fetch rows which can be mapped to a struct implements the `Model` trait. 
+The later ist used to fetch arbitrary rows.
+
+## Example
+
+Just create a `Query` and use the `Query::declare` method to create Declare Statement. 
+This can be used to configure the Cursor and provides Methods to construct a cursor then.
+
+```rust
+use rwf::prelude;
+use rwf::model::prelude::*;
+#[derive(Clone, macros::Model, Serialize, Deserialize)]
+struct User {
+    id: Option<i64>,
+    name: String,
+    mail: String
+}
+#[tokio::main]
+async fn main() -> Result<(), rwf::model::Error> {
+    let mut cursor = User::all()
+        .filter_not_ends_with("mail", ".tld") 
+        .order_by(("id", "asc")) // Always Order the underlying query to make results reproducible 
+        .declare("cursor_name") // Give the cursor a name to refer in FETCH Queries
+        .asensitive() // Make Table changes like inserts available to the cursor
+        .scroll() // Allow all kind of fetches. If not sepcified only forward directed fetches are allowed
+        .hold() // Allow creation outside a transaction. 
+        .create_tx_model_cursor(None) // Creat3 a cursor which fetches the Queries Model. Create a new transaction for the cursor. 
+        .await?;
+    let first_user = cursor.fetch_one(cursor.fetch_stmt().next()).await?;
+    Ok(())
+}
+```

examples/cursor/README.md

@@ -0,0 +1 @@
+DROP TABLE app_logs;

examples/cursor/migrations/1_applog.down.sql

@@ -0,0 +1,7 @@
+CREATE TABLE app_logs (
+    id bigserial primary key,
+    ts timestamptz not null default NOW(),
+    data text not null
+);
+
+INSERT INTO app_logs(data) VALUES ('TTest Entr'), ('Is it working'), ('Last on page one'), ('This is going to be on page two');

examples/cursor/migrations/1_applog.up.sql

@@ -0,0 +1,2 @@
+[database]
+name = "rwf_cursor"

examples/cursor/rwf.toml

@@ -0,0 +1,99 @@
+use rwf::controller::TurboStream;
+use rwf::model::migrate;
+use rwf::model::pool::Transaction;
+use rwf::model::prelude::*;
+use rwf::prelude::*;
+use std::collections::BTreeMap;
+use std::str::FromStr;
+use tokio::sync::Mutex;
+
+#[derive(Debug, Clone, Serialize, Deserialize, macros::Model)]
+pub struct AppLog {
+    id: Option<i64>,
+    ts: OffsetDateTime,
+    data: String,
+}
+impl AppLog {
+    pub fn q() -> Scope<Self> {
+        Self::all().order(("id", "asc"))
+    }
+    pub async fn cursor(name: impl ToString, tx: &mut Transaction) -> ModelCursor<Self> {
+        Self::q()
+            .declare_cursor(name)
+            .expect("Static Query is correct")
+            .scroll()
+            .hold()
+            .create_model_cursor(tx)
+            .await
+            .expect("Database is able to serve the request")
+    }
+}
+
+#[derive(Debug, Default)]
+struct TxModelController {
+    cursors: Mutex<BTreeMap<SessionId, ModelCursor<AppLog>>>,
+}
+enum Direction {
+    Next,
+    Prev,
+}
+impl FromStr for Direction {
+    type Err = String;
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s.to_lowercase().as_str() {
+            "next" => Ok(Self::Next),
+            "prev" => Ok(Self::Prev),
+            s => Err(format!("{} is not a valid direction", s)),
+        }
+    }
+}
+static FETCH_CHUNK: i64 = 3;
+#[async_trait]
+impl Controller for TxModelController {
+    async fn handle(&self, request: &Request) -> Result<Response, rwf::controller::Error> {
+        let mut tx = Pool::begin().await?;
+        let sess_id = request.session_id();
+        let cur_name = format!("sess_cur_{}", sess_id.to_string());
+        match request.query().get::<Direction>("direction") {
+            None => {
+                if let Some(old) = self.cursors.lock().await.remove(&sess_id) {
+                    tx.query_cached(old.close_stmt().as_str(), &[]).await?;
+                }
+                self.cursors
+                    .lock()
+                    .await
+                    .insert(sess_id, AppLog::cursor(cur_name, &mut tx).await);
+                tx.commit().await?;
+                render!(request, "templates/index.html")
+            }
+            Some(direction) => {
+                let mut cur = match self.cursors.lock().await.remove(&sess_id) {
+                    None => return Ok(Response::new().redirect(request.path().path())),
+                    Some(cursor) => cursor,
+                }
+                .to_transaction_cursor(tx);
+                let entries = match direction {
+                    Direction::Next => cur.fetch_optional(cur.fetch_stmt().forward(FETCH_CHUNK)),
+                    Direction::Prev => cur.fetch_optional(cur.fetch_stmt().backward(FETCH_CHUNK)),
+                }
+                .await?
+                .unwrap_or(Vec::new());
+                let (cur, tx) = cur.decouple();
+                tx.commit().await?;
+                self.cursors.lock().await.insert(sess_id, cur);
+                Ok(Response::new().turbo_stream(&[turbo_stream!(request, "templates/entries.html", "entries", "entries" => entries).action("replace")]))
+            }
+        }
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), rwf::http::Error> {
+    migrate().await?;
+    rwf::http::server::Server::new(vec![
+        route!("/" => TxModelController),
+        route!("/ws" => TurboStream),
+    ])
+    .launch()
+    .await
+}

examples/cursor/src/main.rs

@@ -0,0 +1,7 @@
+<ul class="list-group" id="entries">
+    <% for entry in entries %>
+    <li class="list-group-item">
+        <%= entry.data %>
+    </li>
+    <% end %>
+</ul>

examples/cursor/templates/entries.html

@@ -0,0 +1,26 @@
+<html>
+    <head>
+        <title>RWF Cursor Example</title>
+        <%- rwf_head %>
+    </head>
+    <body>
+        <%= rwf_turbo_stream("/ws") %>
+        <div class="container">
+            <div class="card">
+                <div class="card-body">
+                    <ul class="list-group" id="entries"></ul>
+                </div>
+                <div class="card-footer">
+                    <form method="get" id="direction-form">
+                        <label for="direction">Direction: </label>
+                        <select id="direction" name="direction">
+                            <option value="next">Next</option>
+                            <option vaLue="prev">Previous</option>
+                        </select>
+                        <input type="submit" value="send">
+                    </form>
+                </div>
+            </div>
+        </div>
+    </body>
+</html>