1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
//! Concurrent-editor tracking.
//!
//! Pairs with the editor lock: the lock prevents conflicting
//! writes; the editing-session model surfaces a banner so people
//! *see* each other before they collide. Every time the editor JS
//! pings the lock heartbeat (`POST /cms-admin/pages/{id}/lock-heartbeat`),
//! we also touch a row in `cms_editing_session` so a separate JSON
//! endpoint can list the other active viewers/editors.
//!
//! ## Liveness
//!
//! A session is "active" when `last_seen_at` is within the last
//! [`ACTIVE_WINDOW_SECS`] seconds. Older rows are garbage-collected
//! lazily on heartbeat. The GC threshold is 1 hour — long enough to survive transient network blips, short
//! enough that a closed-tab session falls off in reasonable time.
//!
//! ## "Viewing" vs "Editing"
//!
//! The `is_editing` boolean is a hint, not a hard guarantee. The
//! editor JS sets it `true` once the form is touched (any `input`
//! event) and resets it on every page load. Useful UX signal —
//! "alice is editing" reads more urgent than "alice is viewing".
use chrono::{DateTime, Utc};
use rustango::sql::Auto;
use rustango::Model;
use serde::{Deserialize, Serialize};
/// How long a session row counts as "active". Stale rows past this
/// window are filtered out of the JSON response and reaped on the
/// next heartbeat.
pub const ACTIVE_WINDOW_SECS: i64 = 90;
/// Rows older than this are garbage-collected on heartbeat — long
/// past the active window so transient outages don't lose sessions
/// the editor would otherwise rejoin.
pub const GC_THRESHOLD_SECS: i64 = 60 * 60;
#[derive(Model, Debug, Clone, Serialize, Deserialize)]
#[rustango(
table = "cms_editing_session",
app = "cms",
display = "user_id",
admin(
list_display = "page_id, user_id, is_editing, last_seen_at",
ordering = "-last_seen_at",
list_filter = "page_id, is_editing",
)
)]
pub struct EditingSession {
#[rustango(primary_key)]
pub id: Auto<i64>,
#[rustango(fk = "cms_page", on = "id", index)]
pub page_id: i64,
#[rustango(fk = "rustango_users", on = "id", index)]
pub user_id: i64,
/// Bumped by each heartbeat. The active-vs-stale gate compares
/// this against `now() - ACTIVE_WINDOW_SECS`.
pub last_seen_at: DateTime<Utc>,
/// `true` once the editor JS has detected a form touch on this
/// page. Set by the heartbeat ping body (`?is_editing=1`) and
/// reset to `false` on a fresh page load.
pub is_editing: bool,
}
/// UPSERT the heartbeat row for `(page_id, user_id)` and bump
/// `last_seen_at` to now. Application-enforced uniqueness — we
/// don't have a SQL UNIQUE constraint because not every dialect
/// agrees on composite uniqueness syntax. The race window is small
/// enough that the worst-case duplicate row is fine; the GC drops
/// them.
///
/// # Errors
/// Driver / query failures.
pub async fn touch(
pool: &rustango::sql::Pool,
page_id: i64,
user_id: i64,
is_editing: bool,
) -> Result<(), rustango::sql::ExecError> {
use rustango::core::Column as _;
use rustango::sql::FetcherPool as _;
let existing: Vec<EditingSession> = EditingSession::objects()
.where_(EditingSession::page_id.eq(page_id))
.where_(EditingSession::user_id.eq(user_id))
.fetch(pool)
.await?;
if let Some(mut row) = existing.into_iter().next() {
row.last_seen_at = Utc::now();
// `is_editing` is sticky-true within a session: once any
// ping reports editing, the row stays editing until a fresh
// page-load resets it. Reduces UI flicker between viewing
// and editing banners.
if is_editing {
row.is_editing = true;
}
row.save_pool(pool).await?;
} else {
let mut row = EditingSession {
id: Auto::Unset,
page_id,
user_id,
last_seen_at: Utc::now(),
is_editing,
};
row.insert_pool(pool).await?;
}
Ok(())
}
/// Other active sessions on this page (viewer's own session filtered
/// out). Returns `(user_id, last_seen_at, is_editing)` tuples sorted
/// by `last_seen_at` desc.
///
/// # Errors
/// Driver / query failures.
pub async fn others_on_page(
pool: &rustango::sql::Pool,
page_id: i64,
viewer_id: i64,
) -> Result<Vec<EditingSession>, rustango::sql::ExecError> {
use rustango::core::Column as _;
use rustango::sql::FetcherPool as _;
let cutoff = Utc::now() - chrono::Duration::seconds(ACTIVE_WINDOW_SECS);
let rows: Vec<EditingSession> = EditingSession::objects()
.where_(EditingSession::page_id.eq(page_id))
.where_(EditingSession::user_id.ne(viewer_id))
.order_by(&[("last_seen_at", true)]) // desc
.fetch(pool)
.await?;
Ok(rows
.into_iter()
.filter(|r| r.last_seen_at >= cutoff)
.collect())
}
/// Garbage-collect rows older than [`GC_THRESHOLD_SECS`]. Called
/// from the heartbeat handler so the table doesn't grow unbounded
/// — we don't need a cron.
///
/// # Errors
/// Driver / query failures.
pub async fn gc_stale(pool: &rustango::sql::Pool) -> Result<usize, rustango::sql::ExecError> {
use rustango::core::Column as _;
use rustango::sql::FetcherPool as _;
let cutoff = Utc::now() - chrono::Duration::seconds(GC_THRESHOLD_SECS);
let stale: Vec<EditingSession> = EditingSession::objects()
.where_(EditingSession::last_seen_at.lt(cutoff))
.fetch(pool)
.await?;
let count = stale.len();
for row in stale {
row.delete_pool(pool).await?;
}
Ok(count)
}