refactor: move session management to global level (#113)

* refactor: move session management to global manager

- Replace per-captcha session managers with single global session manager
- Sessions are now managed by SPOA instead of individual Captcha instances
- Reduces goroutine overhead (one GC goroutine instead of N per host)
- Simplifies reload logic (sessions persist automatically)
- Prepares architecture for AppSec session integration
- Captcha now only handles cookie generation from UUIDs

* refactor: remove unused context from captcha and appsec initialization

- Remove Cancel field from Captcha struct (never used during requests)
- Remove ctx parameter from Captcha.Init() and AppSec.Init()
- Remove Cancel() calls since there's no cleanup needed
- Validate() uses context.Background() so it's not affected by reloads
- Sessions persist in global manager, so no context lifecycle needed

* refactor: extract session/cookie creation and improve captcha resilience

- Extract session and cookie creation logic into createNewSessionAndCookie helper
- Use helper in both initial session creation and session recovery after reload
- Make URL reading non-critical for captcha remediation (only affects redirect)
- Improve error messages to clarify critical vs non-critical failures
- Ensure captcha remediation is preferred when captcha is configured, only falling back on truly critical failures

Author: LaurenceJJones

cmd/root.go

@@ -18,6 +18,7 @@ import (
 	"github.com/spf13/pflag"
 	"golang.org/x/sync/errgroup"
 
+	"github.com/crowdsecurity/crowdsec-spoa/internal/session"
 	"github.com/crowdsecurity/crowdsec-spoa/pkg/cfg"
 	"github.com/crowdsecurity/crowdsec-spoa/pkg/dataset"
 	"github.com/crowdsecurity/crowdsec-spoa/pkg/host"
@@ -162,6 +163,15 @@ func Execute() error {
 	hostManagerLogger := log.WithField("component", "host_manager")
 	HostManager := host.NewManager(hostManagerLogger)
 
+	// Create and initialize global session manager (single GC goroutine for all hosts)
+	globalSessions := &session.Sessions{
+		SessionIdleTimeout:    "1h", // Default values
+		SessionMaxTime:        "12h",
+		SessionGarbageSeconds: 60,
+	}
+	sessionLogger := log.WithField("component", "global_sessions")
+	globalSessions.Init(sessionLogger, ctx)
+
 	g.Go(func() error {
 		HostManager.Run(ctx)
 		return nil
@@ -185,12 +195,13 @@ func Execute() error {
 
 	// Create single SPOA directly with minimal configuration
 	spoaConfig := &spoa.SpoaConfig{
-		TcpAddr:     config.ListenTCP,
-		UnixAddr:    config.ListenUnix,
-		Dataset:     dataSet,
-		HostManager: HostManager,
-		GeoDatabase: &config.Geo,
-		Logger:      spoaLogger,
+		TcpAddr:        config.ListenTCP,
+		UnixAddr:       config.ListenUnix,
+		Dataset:        dataSet,
+		HostManager:    HostManager,
+		GeoDatabase:    &config.Geo,
+		GlobalSessions: globalSessions,
+		Logger:         spoaLogger,
 	}
 
 	singleSpoa, err := spoa.New(spoaConfig)

internal/appsec/root.go

@@ -1,8 +1,6 @@
 package appsec
 
 import (
-	"context"
-
 	log "github.com/sirupsen/logrus"
 )
 
@@ -11,7 +9,7 @@ type AppSec struct {
 	logger     *log.Entry `yaml:"-"`
 }
 
-func (a *AppSec) Init(logger *log.Entry, ctx context.Context) error {
+func (a *AppSec) Init(logger *log.Entry) error {
 	a.InitLogger(logger)
 	return nil
 }

internal/remediation/captcha/root.go

@@ -13,7 +13,6 @@ import (
 
 	"github.com/crowdsecurity/crowdsec-spoa/internal/cookie"
 	"github.com/crowdsecurity/crowdsec-spoa/internal/remediation"
-	"github.com/crowdsecurity/crowdsec-spoa/internal/session"
 	"github.com/negasus/haproxy-spoe-go/action"
 	log "github.com/sirupsen/logrus"
 )
@@ -35,18 +34,13 @@ type Captcha struct {
 	FallbackRemediation string                 `yaml:"fallback_remediation"` // if captcha configuration is invalid what should we fallback too
 	Timeout             int                    `yaml:"timeout"`              // HTTP client timeout in seconds (default: 5)
 	CookieGenerator     cookie.CookieGenerator `yaml:"cookie"`               // CookieGenerator to generate cookies from sessions
-	Sessions            session.Sessions       `yaml:",inline"`              // sessions that are being traced for captcha
 	logger              *log.Entry             `yaml:"-"`
 	client              *http.Client           `yaml:"-"`
-	Cancel              context.CancelFunc     `yaml:"-"`
 }
 
-func (c *Captcha) Init(logger *log.Entry, ctx context.Context) error {
+func (c *Captcha) Init(logger *log.Entry) error {
 	c.InitLogger(logger)
 
-	var cancelCtx context.Context
-	cancelCtx, c.Cancel = context.WithCancel(ctx)
-
 	// Clone the default transport to preserve proxy settings and other defaults
 	transport := http.DefaultTransport.(*http.Transport).Clone()
 
@@ -76,7 +70,7 @@ func (c *Captcha) Init(logger *log.Entry, ctx context.Context) error {
 		return err
 	}
 
-	c.Sessions.Init(c.logger, cancelCtx)
+	// Initialize cookie generator (sessions are managed by SPOA, not captcha)
 	c.CookieGenerator.Init(c.logger, "crowdsec_captcha_cookie", c.SecretKey)
 
 	return nil

pkg/host/root.go

@@ -99,6 +99,7 @@ func (h *Manager) MatchFirstHost(toMatch string) *Host {
 }
 
 func (h *Manager) Run(ctx context.Context) {
+
 	for {
 		select {
 		case instruction := <-h.Chan:
@@ -109,7 +110,7 @@ func (h *Manager) Run(ctx context.Context) {
 				h.removeHost(instruction.Host)
 			case OpAdd:
 				h.cache = make(map[string]*Host)
-				h.addHost(ctx, instruction.Host)
+				h.addHost(instruction.Host)
 				h.sort()
 			case OpPatch:
 				h.patchHost(instruction.Host)
@@ -179,7 +180,7 @@ func (h *Manager) sort() {
 func (h *Manager) removeHost(host *Host) {
 	for i, th := range h.Hosts {
 		if th == host {
-			host.Captcha.Cancel()
+			// Sessions persist in global manager, no cleanup needed
 			if i == len(h.Hosts)-1 {
 				h.Hosts = h.Hosts[:i]
 			} else {
@@ -228,7 +229,7 @@ func (h *Manager) createHostLogger(host *Host) *log.Entry {
 	return hostLogger.WithField("host", host.Host)
 }
 
-func (h *Manager) addHost(ctx context.Context, host *Host) {
+func (h *Manager) addHost(host *Host) {
 	// Create a logger for this host that inherits base logger values
 	host.logger = h.createHostLogger(host)
 
@@ -238,13 +239,14 @@ func (h *Manager) addHost(ctx context.Context, host *Host) {
 		"has_ban":     true, // Ban is always available
 	})
 
-	if err := host.Captcha.Init(host.logger, ctx); err != nil {
+	// Initialize captcha (no longer needs sessions - SPOA handles that)
+	if err := host.Captcha.Init(host.logger); err != nil {
 		host.logger.Error(err)
 	}
 	if err := host.Ban.Init(host.logger); err != nil {
 		host.logger.Error(err)
 	}
-	if err := host.AppSec.Init(host.logger, ctx); err != nil {
+	if err := host.AppSec.Init(host.logger); err != nil {
 		host.logger.Error(err)
 	}
 	h.Hosts = append(h.Hosts, host)

pkg/spoa/root.go

@@ -37,18 +37,20 @@ type Spoa struct {
 	HAWaitGroup  *sync.WaitGroup
 	logger       *log.Entry
 	// Direct access to shared data (no IPC needed)
-	dataset     *dataset.DataSet
-	hostManager *host.Manager
-	geoDatabase *geo.GeoDatabase
+	dataset        *dataset.DataSet
+	hostManager    *host.Manager
+	geoDatabase    *geo.GeoDatabase
+	globalSessions *session.Sessions // Global session manager for all hosts
 }
 
 type SpoaConfig struct {
-	TcpAddr     string
-	UnixAddr    string
-	Dataset     *dataset.DataSet
-	HostManager *host.Manager
-	GeoDatabase *geo.GeoDatabase
-	Logger      *log.Entry // Parent logger to inherit from
+	TcpAddr        string
+	UnixAddr       string
+	Dataset        *dataset.DataSet
+	HostManager    *host.Manager
+	GeoDatabase    *geo.GeoDatabase
+	GlobalSessions *session.Sessions // Global session manager for all hosts
+	Logger         *log.Entry        // Parent logger to inherit from
 }
 
 func New(config *SpoaConfig) (*Spoa, error) {
@@ -71,11 +73,12 @@ func New(config *SpoaConfig) (*Spoa, error) {
 	// No worker-specific log level; inherits from parent logger
 
 	s := &Spoa{
-		HAWaitGroup: &sync.WaitGroup{},
-		logger:      workerLogger,
-		dataset:     config.Dataset,
-		hostManager: config.HostManager,
-		geoDatabase: config.GeoDatabase,
+		HAWaitGroup:    &sync.WaitGroup{},
+		logger:         workerLogger,
+		dataset:        config.Dataset,
+		hostManager:    config.HostManager,
+		geoDatabase:    config.GeoDatabase,
+		globalSessions: config.GlobalSessions,
 	}
 
 	if config.TcpAddr != "" {
@@ -402,6 +405,47 @@ func parseHTTPData(logger *log.Entry, mes *message.Message) HTTPRequestData {
 	return httpData
 }
 
+// createNewSessionAndCookie creates a new session, generates a cookie, and sets it in the request.
+// Returns the session, uuid, and an error if any step fails.
+func (s *Spoa) createNewSessionAndCookie(req *request.Request, mes *message.Message, matchedHost *host.Host) (*session.Session, string, error) {
+	ssl, err := readKeyFromMessage[bool](mes, "ssl")
+	if err != nil {
+		s.logger.WithFields(log.Fields{
+			"error": err,
+			"key":   "ssl",
+		}).Warn("failed to read ssl flag from message, cookie secure flag will default to false - ensure HAProxy is sending the 'ssl_fc' variable as 'ssl' in crowdsec-http message")
+	}
+
+	// Create a new session using global session manager
+	ses, err := s.globalSessions.NewRandomSession()
+	if err != nil {
+		s.logger.WithFields(log.Fields{
+			"host":  matchedHost.Host,
+			"error": err,
+		}).Error("Failed to create new session")
+		return nil, "", err
+	}
+
+	cookie, err := matchedHost.Captcha.CookieGenerator.GenerateCookie(ses, ssl)
+	if err != nil {
+		s.logger.WithFields(log.Fields{
+			"host":  matchedHost.Host,
+			"ssl":   ssl,
+			"error": err,
+		}).Error("Failed to generate host cookie")
+		return nil, "", err
+	}
+
+	// Set initial captcha status to pending
+	ses.Set(session.CaptchaStatus, captcha.Pending)
+	uuid := ses.UUID
+
+	// Set the captcha cookie - status will be set later based on session state
+	req.Actions.SetVar(action.ScopeTransaction, "captcha_cookie", cookie.String())
+
+	return ses, uuid, nil
+}
+
 // handleCaptchaRemediation handles all captcha-related logic including cookie validation,
 // session management, captcha validation, and status updates.
 // Returns the remediation and parsed HTTP request data for reuse in AppSec processing.
@@ -433,40 +477,18 @@ func (s *Spoa) handleCaptchaRemediation(req *request.Request, mes *message.Messa
 	}
 
 	if uuid == "" {
-		ssl, err := readKeyFromMessage[bool](mes, "ssl")
-		if err != nil {
-			s.logger.WithFields(log.Fields{
-				"error": err,
-				"key":   "ssl",
-			}).Warn("failed to read ssl flag from message, cookie secure flag will default to false - ensure HAProxy is sending the 'ssl_fc' variable as 'ssl' in crowdsec-http message")
-		}
-
-		// Create a new session
-		ses, err = matchedHost.Captcha.Sessions.NewRandomSession()
-		if err != nil {
-			s.logger.WithFields(log.Fields{
-				"host":  matchedHost.Host,
-				"error": err,
-			}).Error("Failed to create new session")
-			return remediation.FromString(matchedHost.Captcha.FallbackRemediation), HTTPRequestData{}
-		}
-
-		cookie, err := matchedHost.Captcha.CookieGenerator.GenerateCookie(ses, ssl)
+		// No valid cookie, create new session and cookie
+		var err error
+		ses, uuid, err = s.createNewSessionAndCookie(req, mes, matchedHost)
 		if err != nil {
+			// Session creation is critical for captcha to work - without it we can't track captcha status
+			// This is a critical failure, so we must fall back to fallback remediation
 			s.logger.WithFields(log.Fields{
 				"host":  matchedHost.Host,
-				"ssl":   ssl,
 				"error": err,
-			}).Error("Failed to generate host cookie")
+			}).Error("Failed to create new session and cookie, falling back to fallback remediation")
 			return remediation.FromString(matchedHost.Captcha.FallbackRemediation), HTTPRequestData{}
 		}
-
-		// Set initial captcha status to pending
-		ses.Set(session.CaptchaStatus, captcha.Pending)
-		uuid = ses.UUID
-
-		// Set the captcha cookie - status will be set later based on session state
-		req.Actions.SetVar(action.ScopeTransaction, "captcha_cookie", cookie.String())
 	}
 
 	if uuid == "" {
@@ -476,25 +498,26 @@ func (s *Spoa) handleCaptchaRemediation(req *request.Request, mes *message.Messa
 		return remediation.FromString(matchedHost.Captcha.FallbackRemediation), HTTPRequestData{}
 	}
 
-	url, err := readKeyFromMessage[string](mes, "url")
-	if err != nil {
-		s.logger.WithFields(log.Fields{
-			"error": err,
-			"key":   "url",
-			"host":  matchedHost.Host,
-		}).Error("failed to read url from message, cannot proceed with captcha remediation - ensure HAProxy is sending the 'url' variable in crowdsec-http message")
-		return remediation.FromString(matchedHost.Captcha.FallbackRemediation), HTTPRequestData{}
-	}
-
 	// Get the session only if we didn't just create it (i.e., we have an existing cookie)
 	if ses == nil {
-		ses = matchedHost.Captcha.Sessions.GetSession(uuid)
+		ses = s.globalSessions.GetSession(uuid)
 		if ses == nil {
+			// Session lost from memory (e.g., after reload), create a new session and cookie
 			s.logger.WithFields(log.Fields{
 				"host":    matchedHost.Host,
 				"session": uuid,
-			}).Warn("Session not found, cannot proceed with captcha")
-			return remediation.FromString(matchedHost.Captcha.FallbackRemediation), HTTPRequestData{}
+			}).Warn("Session not found in memory (likely lost after reload), creating new session and cookie")
+			var err error
+			ses, uuid, err = s.createNewSessionAndCookie(req, mes, matchedHost)
+			if err != nil {
+				// Session creation is critical for captcha to work - without it we can't track captcha status
+				// This is a critical failure, so we must fall back to fallback remediation
+				s.logger.WithFields(log.Fields{
+					"host":  matchedHost.Host,
+					"error": err,
+				}).Error("Failed to create new session after reload, falling back to fallback remediation")
+				return remediation.FromString(matchedHost.Captcha.FallbackRemediation), HTTPRequestData{}
+			}
 		}
 	}
 
@@ -506,15 +529,25 @@ func (s *Spoa) handleCaptchaRemediation(req *request.Request, mes *message.Messa
 
 	// Set the captcha status in the transaction for HAProxy
 	req.Actions.SetVar(action.ScopeTransaction, "captcha_status", captchaStatus)
-	if captchaStatus != captcha.Valid {
+
+	// Read URL - this is not critical for showing the captcha page, only for redirect after validation
+	url, err := readKeyFromMessage[string](mes, "url")
+	if err != nil {
+		s.logger.WithFields(log.Fields{
+			"error": err,
+			"key":   "url",
+			"host":  matchedHost.Host,
+		}).Warn("failed to read url from message, captcha will still be shown but redirect after validation may not work - ensure HAProxy is sending the 'url' variable in crowdsec-http message")
+		// Continue with captcha even without URL - we just won't be able to redirect after validation
+	} else if captchaStatus != captcha.Valid && url != nil {
 		// Update the incoming url if it is different from the stored url for the session ignore favicon requests
 		storedURL := ses.Get(session.URI)
 		if storedURL == nil {
 			storedURL = ""
 		}
 
 		// Check url is not nil before dereferencing
-		if url != nil && (storedURL == "" || *url != storedURL) && !strings.HasSuffix(*url, ".ico") {
+		if (storedURL == "" || *url != storedURL) && !strings.HasSuffix(*url, ".ico") {
 			s.logger.WithField("session", uuid).Debugf("updating stored url %s", *url)
 			ses.Set(session.URI, *url)
 		}