feat: add session idle timeout cleanup goroutine

- Periodic cleanup loop deletes stale clients based on SESSION_IDLE_TIMEOUT - Orphaned sessions (no clients) are cleaned up automatically - last_seen already updated on each authenticated request via GetSessionByToken
feat: add SESSION_IDLE_TIMEOUT config
2026-02-28 11:00:06 -08:00 · 2026-02-28 11:00:06 -08:00 · 2026-02-28 11:00:06 -08:00
6 changed files with 29 additions and 242 deletions
--- a/19
+++ b/19
@@ -1,35 +1,24 @@
-# Lint stage — fast feedback on formatting and lint issues
-# golangci/golangci-lint:v2.1.6, 2026-03-02
-FROM golangci/golangci-lint@sha256:568ee1c1c53493575fa9494e280e579ac9ca865787bafe4df3023ae59ecf299b AS lint
-WORKDIR /src
-COPY go.mod go.sum ./
-RUN go mod download
-COPY . .
-RUN make fmt-check
-RUN make lint
-
-# Build stage
 # golang:1.24-alpine, 2026-02-26
 FROM golang@sha256:8bee1901f1e530bfb4a7850aa7a479d17ae3a18beb6e09064ed54cfd245b7191 AS builder
 WORKDIR /src
 RUN apk add --no-cache git build-base make

-# Force BuildKit to run the lint stage before proceeding
-COPY --from=lint /src/go.sum /dev/null
+# golangci-lint v2.1.6 (eabc2638a66d), 2026-02-26
+RUN CGO_ENABLED=0 go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@eabc2638a66daf5bb6c6fb052a32fa3ef7b6600d

 COPY go.mod go.sum ./
 RUN go mod download

 COPY . .

-RUN make test
+# Run all checks — build fails if branch is not green
+RUN make check

 # Build static binaries (no cgo needed at runtime — modernc.org/sqlite is pure Go)
 ARG VERSION=dev
 RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w -X main.Version=${VERSION}" -o /chatd ./cmd/chatd/
 RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /chat-cli ./cmd/chat-cli/

-# Runtime stage
 # alpine:3.21, 2026-02-26
 FROM alpine@sha256:c3f8e73fdb79deaebaa2037150150191b9dcbfba68b4a46d70103204c53f4709
 RUN apk add --no-cache ca-certificates \
--- a/README.md
+++ b/README.md
@@ -1158,55 +1158,6 @@ curl -s http://localhost:8080/api/v1/channels/general/members \
  -H "Authorization: Bearer $TOKEN" | jq .
 ```

-### POST /api/v1/logout — Logout
-
-Destroy the current client's auth token. If no other clients remain on the
-session, the user is fully cleaned up: parted from all channels (with QUIT
-broadcast to members), session deleted, nick released.
-
-**Request:** No body. Requires auth.
-
-**Response:** `200 OK`
-```json
-{"status": "ok"}
-```
-
-**Errors:**
-
-| Status | Error | When |
-|--------|-------|------|
-| 401    | `unauthorized` | Missing or invalid auth token |
-
-**curl example:**
-```bash
-curl -s -X POST http://localhost:8080/api/v1/logout \
-  -H "Authorization: Bearer $TOKEN" | jq .
-```
-
-### GET /api/v1/users/me — Current User Info
-
-Return the current user's session state. This is an alias for
-`GET /api/v1/state`.
-
-**Request:** No body. Requires auth.
-
-**Response:** `200 OK`
-```json
-{
-  "id": 1,
-  "nick": "alice",
-  "channels": [
-    {"id": 1, "name": "#general", "topic": "Welcome!"}
-  ]
-}
-```
-
-**curl example:**
-```bash
-curl -s http://localhost:8080/api/v1/users/me \
-  -H "Authorization: Bearer $TOKEN" | jq .
-```
-
 ### GET /api/v1/server — Server Info

 Return server metadata. No authentication required.
@@ -1215,17 +1166,10 @@ Return server metadata. No authentication required.
 ```json
 {
  "name": "My Chat Server",
-  "motd": "Welcome! Be nice.",
-  "users": 42
+  "motd": "Welcome! Be nice."
 }
 ```

-| Field   | Type    | Description |
-|---------|---------|-------------|
-| `name`  | string  | Server display name |
-| `motd`  | string  | Message of the day |
-| `users` | integer | Number of currently active user sessions |
-
 ### GET /.well-known/healthcheck.json — Health Check

 Standard health check endpoint. No authentication required.
@@ -1628,10 +1572,8 @@ skew issues) and simpler than UUIDs (integer comparison vs. string comparison).
 - **Queue entries**: Stored until pruned. Pruning by `QUEUE_MAX_AGE` is
  planned.
 - **Channels**: Deleted when the last member leaves (ephemeral).
- **Users/sessions**: Deleted on `QUIT` or `POST /api/v1/logout`. Idle
-  sessions are automatically expired after `SESSION_IDLE_TIMEOUT` (default
-  24h) — the server runs a background cleanup loop that parts idle users
-  from all channels, broadcasts QUIT, and releases their nicks.
+- **Users/sessions**: Deleted on `QUIT`. Session expiry by `SESSION_TIMEOUT`
+  is planned.

 ---

@@ -1648,7 +1590,7 @@ directory is also loaded automatically via
 | `DBURL`            | string  | `file:./data.db?_journal_mode=WAL`   | SQLite connection string. For file-based: `file:./path.db?_journal_mode=WAL`. For in-memory (testing): `file::memory:?cache=shared`. |
 | `DEBUG`            | bool    | `false`                              | Enable debug logging (verbose request/response logging) |
 | `MAX_HISTORY`      | int     | `10000`                              | Maximum messages retained per channel before rotation (planned) |
-| `SESSION_IDLE_TIMEOUT` | string | `24h`                            | Session idle timeout as a Go duration string (e.g. `24h`, `30m`). Sessions with no activity for this long are expired and the nick is released. |
+| `SESSION_TIMEOUT`  | int     | `86400`                              | Session idle timeout in seconds (planned). Sessions with no activity for this long are expired and the nick is released. |
 | `QUEUE_MAX_AGE`    | int     | `172800`                             | Maximum age of client queue entries in seconds (48h). Entries older than this are pruned (planned). |
 | `MAX_MESSAGE_SIZE` | int     | `4096`                               | Maximum message body size in bytes (planned enforcement) |
 | `LONG_POLL_TIMEOUT`| int     | `15`                                 | Default long-poll timeout in seconds (client can override via query param, server caps at 30) |
@@ -1668,7 +1610,7 @@ SERVER_NAME=My Chat Server
 MOTD=Welcome! Be excellent to each other.
 DEBUG=false
 DBURL=file:./data.db?_journal_mode=WAL
-SESSION_IDLE_TIMEOUT=24h
+SESSION_TIMEOUT=86400
 ```

 ---
@@ -2066,14 +2008,11 @@ GET /api/v1/challenge
 - [x] Docker deployment
 - [x] Prometheus metrics endpoint
 - [x] Health check endpoint
- [x] Session expiry — auto-expire idle sessions, release nicks
- [x] Logout endpoint (`POST /api/v1/logout`)
- [x] Current user endpoint (`GET /api/v1/users/me`)
- [x] User count in server info (`GET /api/v1/server`)

 ### Post-MVP (Planned)

 - [ ] **Hashcash proof-of-work** for session creation (abuse prevention)
+- [ ] **Session expiry** — auto-expire idle sessions, release nicks
 - [ ] **Queue pruning** — delete old queue entries per `QUEUE_MAX_AGE`
 - [ ] **Message rotation** — enforce `MAX_HISTORY` per channel
 - [ ] **Channel modes** — enforce `+i`, `+m`, `+s`, `+t`, `+n`
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -31,6 +31,7 @@ type Config struct {
 	Port               int
 	SentryDSN          string
 	MaxHistory         int
+	SessionTimeout     int
 	MaxMessageSize     int
 	MOTD               string
 	ServerName         string
@@ -61,6 +62,7 @@ func New(
 	viper.SetDefault("METRICS_USERNAME", "")
 	viper.SetDefault("METRICS_PASSWORD", "")
 	viper.SetDefault("MAX_HISTORY", "10000")
+	viper.SetDefault("SESSION_TIMEOUT", "86400")
 	viper.SetDefault("MAX_MESSAGE_SIZE", "4096")
 	viper.SetDefault("MOTD", "")
 	viper.SetDefault("SERVER_NAME", "")
@@ -85,6 +87,7 @@ func New(
 		MetricsUsername:    viper.GetString("METRICS_USERNAME"),
 		MetricsPassword:    viper.GetString("METRICS_PASSWORD"),
 		MaxHistory:         viper.GetInt("MAX_HISTORY"),
+		SessionTimeout:     viper.GetInt("SESSION_TIMEOUT"),
 		MaxMessageSize:     viper.GetInt("MAX_MESSAGE_SIZE"),
 		MOTD:               viper.GetString("MOTD"),
 		ServerName:         viper.GetString("SERVER_NAME"),
--- a/internal/db/queries.go
+++ b/internal/db/queries.go
@@ -796,8 +796,8 @@ func (database *Database) DeleteClient(
 	return nil
 }

-// GetUserCount returns the number of active users.
-func (database *Database) GetUserCount(
+// GetSessionCount returns the number of active sessions.
+func (database *Database) GetSessionCount(
 	ctx context.Context,
 ) (int64, error) {
 	var count int64
@@ -808,7 +808,7 @@ func (database *Database) GetUserCount(
 	).Scan(&count)
 	if err != nil {
 		return 0, fmt.Errorf(
-			"get user count: %w", err,
+			"get session count: %w", err,
 		)
 	}

@@ -838,9 +838,9 @@ func (database *Database) ClientCountForSession(
 	return count, nil
 }

-// DeleteStaleUsers removes clients not seen since the
-// cutoff and cleans up orphaned users (sessions).
-func (database *Database) DeleteStaleUsers(
+// DeleteStaleSessions removes clients not seen since the
+// cutoff and cleans up orphaned sessions.
+func (database *Database) DeleteStaleSessions(
 	ctx context.Context,
 	cutoff time.Time,
 ) (int64, error) {
@@ -869,60 +869,6 @@ func (database *Database) DeleteStaleUsers(
 	return deleted, nil
 }

-// StaleSession holds the id and nick of a session
-// whose clients are all stale.
-type StaleSession struct {
-	ID   int64
-	Nick string
-}
-
-// GetStaleOrphanSessions returns sessions where every
-// client has a last_seen before cutoff.
-func (database *Database) GetStaleOrphanSessions(
-	ctx context.Context,
-	cutoff time.Time,
-) ([]StaleSession, error) {
-	rows, err := database.conn.QueryContext(ctx,
-		`SELECT s.id, s.nick
-		 FROM sessions s
-		 WHERE s.id IN (
-		   SELECT DISTINCT session_id FROM clients
-		   WHERE last_seen < ?
-		 )
-		 AND s.id NOT IN (
-		   SELECT DISTINCT session_id FROM clients
-		   WHERE last_seen >= ?
-		 )`, cutoff, cutoff)
-	if err != nil {
-		return nil, fmt.Errorf(
-			"get stale orphan sessions: %w", err,
-		)
-	}
-
-	defer func() { _ = rows.Close() }()
-
-	var result []StaleSession
-
-	for rows.Next() {
-		var stale StaleSession
-		if err := rows.Scan(&stale.ID, &stale.Nick); err != nil {
-			return nil, fmt.Errorf(
-				"scan stale session: %w", err,
-			)
-		}
-
-		result = append(result, stale)
-	}
-
-	if err := rows.Err(); err != nil {
-		return nil, fmt.Errorf(
-			"iterate stale sessions: %w", err,
-		)
-	}
-
-	return result, nil
-}
-
 // GetSessionChannels returns channels a session
 // belongs to.
 func (database *Database) GetSessionChannels(
--- a/internal/handlers/api.go
+++ b/internal/handlers/api.go
@@ -1361,23 +1361,20 @@ func (hdlr *Handlers) canAccessChannelHistory(
 	return true
 }

-// HandleLogout deletes the authenticated client's token
-// and cleans up the user (session) if no clients remain.
+// HandleLogout deletes the authenticated client's token.
 func (hdlr *Handlers) HandleLogout() http.HandlerFunc {
 	return func(
 		writer http.ResponseWriter,
 		request *http.Request,
 	) {
-		sessionID, clientID, nick, ok :=
+		_, clientID, _, ok :=
 			hdlr.requireAuth(writer, request)
 		if !ok {
 			return
 		}

-		ctx := request.Context()
-
 		err := hdlr.params.Database.DeleteClient(
-			ctx, clientID,
+			request.Context(), clientID,
 		)
 		if err != nil {
 			hdlr.log.Error(
@@ -1392,77 +1389,12 @@ func (hdlr *Handlers) HandleLogout() http.HandlerFunc {
 			return
 		}

-		// If no clients remain, clean up the user fully:
-		// part all channels (notifying members) and
-		// delete the session.
-		remaining, err := hdlr.params.Database.
-			ClientCountForSession(ctx, sessionID)
-		if err != nil {
-			hdlr.log.Error(
-				"client count check failed", "error", err,
-			)
-		}
-
-		if remaining == 0 {
-			hdlr.cleanupUser(
-				ctx, sessionID, nick,
-			)
-		}
-
 		hdlr.respondJSON(writer, request,
 			map[string]string{"status": "ok"},
 			http.StatusOK)
 	}
 }

-// cleanupUser parts the user from all channels (notifying
-// members) and deletes the session.
-func (hdlr *Handlers) cleanupUser(
-	ctx context.Context,
-	sessionID int64,
-	nick string,
-) {
-	channels, _ := hdlr.params.Database.
-		GetSessionChannels(ctx, sessionID)
-
-	notified := map[int64]bool{}
-
-	var quitDBID int64
-
-	if len(channels) > 0 {
-		quitDBID, _, _ = hdlr.params.Database.InsertMessage(
-			ctx, "QUIT", nick, "", nil, nil,
-		)
-	}
-
-	for _, chanInfo := range channels {
-		memberIDs, _ := hdlr.params.Database.
-			GetChannelMemberIDs(ctx, chanInfo.ID)
-
-		for _, mid := range memberIDs {
-			if mid != sessionID && !notified[mid] {
-				notified[mid] = true
-
-				_ = hdlr.params.Database.EnqueueToSession(
-					ctx, mid, quitDBID,
-				)
-
-				hdlr.broker.Notify(mid)
-			}
-		}
-
-		_ = hdlr.params.Database.PartChannel(
-			ctx, chanInfo.ID, sessionID,
-		)
-
-		_ = hdlr.params.Database.DeleteChannelIfEmpty(
-			ctx, chanInfo.ID,
-		)
-	}
-
-	_ = hdlr.params.Database.DeleteSession(ctx, sessionID)
-}
-
 // HandleUsersMe returns the current user's session info.
 func (hdlr *Handlers) HandleUsersMe() http.HandlerFunc {
 	return hdlr.HandleState()
@@ -1474,12 +1406,12 @@ func (hdlr *Handlers) HandleServerInfo() http.HandlerFunc {
 		writer http.ResponseWriter,
 		request *http.Request,
 	) {
-		users, err := hdlr.params.Database.GetUserCount(
+		users, err := hdlr.params.Database.GetSessionCount(
 			request.Context(),
 		)
 		if err != nil {
 			hdlr.log.Error(
-				"get user count failed", "error", err,
+				"get session count failed", "error", err,
 			)
 			hdlr.respondError(
 				writer, request,
--- a/internal/handlers/handlers.go
+++ b/internal/handlers/handlers.go
@@ -124,16 +124,8 @@ func (hdlr *Handlers) idleTimeout() time.Duration {
 	return dur
 }

-// startCleanup launches the idle-user cleanup goroutine.
-// We use context.Background rather than the OnStart ctx
-// because the OnStart context is startup-scoped and would
-// cancel the goroutine once all start hooks complete.
-//
-//nolint:contextcheck // intentional Background ctx
-func (hdlr *Handlers) startCleanup(_ context.Context) {
-	cleanupCtx, cancel := context.WithCancel(
-		context.Background(),
-	)
+func (hdlr *Handlers) startCleanup(ctx context.Context) {
+	cleanupCtx, cancel := context.WithCancel(ctx)
 	hdlr.cancelCleanup = cancel

 	go hdlr.cleanupLoop(cleanupCtx)
@@ -169,26 +161,12 @@ func (hdlr *Handlers) runCleanup(
 ) {
 	cutoff := time.Now().Add(-timeout)

-	// Find sessions that will be orphaned so we can send
-	// QUIT notifications before deleting anything.
-	stale, err := hdlr.params.Database.
-		GetStaleOrphanSessions(ctx, cutoff)
-	if err != nil {
-		hdlr.log.Error(
-			"stale session lookup failed", "error", err,
-		)
-	}
-
-	for _, ss := range stale {
-		hdlr.cleanupUser(ctx, ss.ID, ss.Nick)
-	}
-
-	deleted, err := hdlr.params.Database.DeleteStaleUsers(
+	deleted, err := hdlr.params.Database.DeleteStaleSessions(
 		ctx, cutoff,
 	)
 	if err != nil {
 		hdlr.log.Error(
-			"user cleanup failed", "error", err,
+			"session cleanup failed", "error", err,
 		)

 		return
@@ -196,7 +174,7 @@ func (hdlr *Handlers) runCleanup(

 	if deleted > 0 {
 		hdlr.log.Info(
-			"cleaned up stale users",
+			"cleaned up stale clients",
 			"deleted", deleted,
 		)
 	}