diff --git a/doc/sessions.md b/doc/sessions.md index 68c81d75..213037ec 100644 --- a/doc/sessions.md +++ b/doc/sessions.md @@ -64,6 +64,24 @@ grace deadline; detaching a claimed Request refreshes it, while detaching an unclaimed Request leaves it unchanged. Maintenance removes expired Sessions without attached Requests. Cookies have no explicit expiry or MaxAge. +An application using a Session for authenticated HTTP pages without a WebSocket +can call `Session.Touch` after authorizing each request. It extends the grace +window for a current live Session and returns false for an expired, closed, or +replaced Session. Reject the request when it returns false, and prevent shared +caching of every protected response: + +```go +w.Header().Set("Cache-Control", "no-store") +session := jw.GetSession(r) +if session == nil || !authorized(session) || !session.Touch() { + http.Error(w, "Forbidden", http.StatusForbidden) + return +} +``` + +`authorized` is the application's identity and permission check; `Touch` does +not authorize the request. + `Session.Reload` asks its active pages to reload. `Session.Close` invalidates the Session and queues reloads for its associated pages, including those still waiting to connect. It leaves stored data intact; call `Session.Clear` to remove diff --git a/session.go b/session.go index 29afd899..6667cd12 100644 --- a/session.go +++ b/session.go @@ -19,12 +19,13 @@ import ( const sessionGrace = time.Minute -// Session stores server-side state shared by one or more Requests. +// Session stores server-side state shared by HTTP handlers and JaWS Requests. // // Sessions live in memory and are bound to the remote IP that created them. // Their cookies have no explicit expiry or MaxAge. A Session starts with a -// one-minute grace deadline; detaching a claimed Request refreshes that deadline, -// while detaching an unclaimed Request leaves it unchanged. It expires once the +// one-minute grace deadline; Touch can extend it for authenticated HTTP activity. +// Detaching a claimed Request refreshes that deadline, while detaching an +// unclaimed Request leaves it unchanged. It expires once the // deadline passes with no attached Requests, and maintenance removes it. // [Jaws.Close] invalidates all Sessions and clears their data. // @@ -143,6 +144,26 @@ func (sess *Session) Set(key string, value any) { } } +// Touch extends the one-minute grace window for a current, live Session. +// Applications can call it after authorizing an HTTP request without a WebSocket. +// It returns true when it extends the deadline, and false for a nil, expired, +// closed, or replaced Session. A concurrent Close may invalidate it immediately. +func (sess *Session) Touch() bool { + if sess == nil { + return false + } + jw := sess.jw + jw.mu.RLock() + defer jw.mu.RUnlock() + sess.mu.Lock() + defer sess.mu.Unlock() + if jw.sessions[sess.sessionID] != sess || sess.isDeadLocked() { + return false + } + sess.deadline = time.Now().Add(sessionGrace) + return true +} + // ID returns the session ID, a 64-bit random value. func (sess *Session) ID() (id uint64) { if sess != nil { diff --git a/session_test.go b/session_test.go index 187489cd..6fb437d8 100644 --- a/session_test.go +++ b/session_test.go @@ -8,6 +8,7 @@ import ( "net/http" "net/http/httptest" "net/netip" + "runtime" "slices" "strings" "testing" @@ -2097,6 +2098,174 @@ func TestSession_GetSessionExpiredBeforeCleanup(t *testing.T) { } } +func TestSession_TouchExtendsHTTPGraceAndRejectsExpiry(t *testing.T) { + jw, err := New() + if err != nil { + t.Fatal(err) + } + defer jw.Close() + + r := httptest.NewRequest(http.MethodGet, "http://example.test/", nil) + sess := jw.NewSession(httptest.NewRecorder(), r) + if sess == nil { + t.Fatal("expected session") + } + sess.mu.Lock() + sess.deadline = time.Now().Add(time.Second) + sess.mu.Unlock() + before := time.Now() + if !sess.Touch() { + t.Fatal("current HTTP session was not touched") + } + after := time.Now() + sess.mu.RLock() + refreshed := sess.deadline + sess.mu.RUnlock() + if refreshed.Before(before.Add(sessionGrace)) || refreshed.After(after.Add(sessionGrace)) { + t.Fatalf("Touch deadline outside one-minute grace: before=%s after=%s deadline=%s", before, after, refreshed) + } + if got := jw.GetSession(r); got != sess { + t.Fatalf("touched session not retrievable: got %p, want %p", got, sess) + } + + sess.mu.Lock() + sess.deadline = time.Now().Add(-time.Second) + sess.mu.Unlock() + if sess.Touch() || jw.GetSession(r) != nil { + t.Fatal("Touch revived an expired session") + } + var absent *Session + if absent.Touch() { + t.Fatal("nil Session.Touch succeeded") + } +} + +func TestSession_TouchAttachedRequest(t *testing.T) { + jw, err := New() + if err != nil { + t.Fatal(err) + } + defer jw.Close() + + r := httptest.NewRequest(http.MethodGet, "http://example.test/", nil) + sess := jw.NewSession(httptest.NewRecorder(), r) + if sess == nil { + t.Fatal("expected session") + } + rq := jw.NewRequest(httptest.NewRecorder(), r) + if rq.Session() != sess { + t.Fatal("request did not attach to session") + } + sess.mu.Lock() + sess.deadline = time.Now().Add(-time.Second) + sess.mu.Unlock() + if !sess.Touch() { + t.Fatal("Touch rejected a session kept live by an attached request") + } + jw.recycle(rq) + if got := jw.GetSession(r); got != sess { + t.Fatalf("session expired after unclaimed request detached: got %p, want %p", got, sess) + } +} + +func TestSession_TouchRejectsReplacedAndClosedSession(t *testing.T) { + jw, err := New() + if err != nil { + t.Fatal(err) + } + defer jw.Close() + + const sessionID = key.Key(0x1122334455667788) + remoteIP := netip.MustParseAddr("192.0.2.1") + stale := newSession(jw, sessionID, remoteIP, false) + jw.mu.Lock() + jw.registerSessionLocked(stale, false) + jw.mu.Unlock() + jw.deleteSessionIfCurrent(stale) + + replacement := newSession(jw, sessionID, remoteIP, false) + jw.mu.Lock() + jw.registerSessionLocked(replacement, false) + jw.mu.Unlock() + if stale.Touch() || !replacement.Touch() { + t.Fatal("Touch accepted stale session or rejected current replacement") + } + replacement.Close() + if replacement.Touch() { + t.Fatal("Touch revived a closed session") + } + if stale.Touch() { + t.Fatal("Touch revived a replaced session after current Close") + } +} + +func TestSession_TouchConcurrentReplacement(t *testing.T) { + jw, err := New() + if err != nil { + t.Fatal(err) + } + closeSafe := true + defer func() { + if closeSafe { + jw.Close() + } + }() + + r := httptest.NewRequest(http.MethodGet, "http://example.test/", nil) + old := jw.NewSession(httptest.NewRecorder(), r) + if old == nil { + t.Fatal("expected session") + } + old.mu.Lock() + touched := make(chan bool, 1) + go func() { touched <- old.Touch() }() + // Hold Touch at the session lock while it owns the registry read lock. + deadline := time.Now().Add(5 * time.Second) + for jw.mu.TryLock() { + jw.mu.Unlock() + if time.Now().After(deadline) { + old.mu.Unlock() + closeSafe = false + t.Fatal("Touch did not acquire the registry read lock") + } + runtime.Gosched() + } + replaced := make(chan *Session, 1) + go func() { replaced <- jw.NewSession(httptest.NewRecorder(), r) }() + // A waiting replacement writer blocks new readers until Touch releases it. + deadline = time.Now().Add(5 * time.Second) + for jw.mu.TryRLock() { + jw.mu.RUnlock() + if time.Now().After(deadline) { + old.mu.Unlock() + closeSafe = false + t.Fatal("replacement did not wait for Touch") + } + runtime.Gosched() + } + old.mu.Unlock() + var wasTouched bool + select { + case wasTouched = <-touched: + case <-time.After(5 * time.Second): + closeSafe = false + t.Fatal("Touch remained blocked during replacement") + } + if !wasTouched { + t.Fatal("Touch rejected the current session before replacement") + } + var current *Session + select { + case current = <-replaced: + case <-time.After(5 * time.Second): + closeSafe = false + t.Fatal("replacement remained blocked after Touch") + } + if current == nil || old.Touch() || !current.Touch() || jw.GetSession(r) != current { + t.Fatal("Touch revived the old session after replacement") + } +} + func TestSession_GetSessionRejectsCookieValueWithTail(t *testing.T) { jw, _ := New() defer jw.Close()