notifications: support session invalidations (#65)

- Part of
https://linear.app/sourcegraph/issue/CORE-340/workspaces-sams-session-federation-poc
- Sister PR of
sourcegraph/sourcegraph-accounts#304

Changes in this PR is necessary for
sourcegraph/sourcegraph#1222 to compile.

## Test plan

CI

notifications/v1/subscriber.go

@@ -180,13 +180,20 @@ type SubscriberHandlers struct {
 	// MUST make sure the error is surfaced (by either returning or logging the
 	// error) to be retried or to a human operator.
 	OnUserDeleted func(ctx context.Context, data *UserDeletedData) error
-	// OnUserRolesUpdated is called when a "UserRolesUpdated" notification is received.
+	// OnUserRolesUpdated is called when a "UserRolesUpdated" notification is
+	// received.
 	//
 	// It indicates that a user's roles have been updated for a particular service.
-	// The notification data does not specify whether roles have been granted or revoked.
-	// If the service's roles are relevant to the subscriber the user's current roles can
-	// be retrieved from the SAMS API.
+	// The notification data does not specify whether roles have been granted or
+	// revoked. If the service's roles are relevant to the subscriber the user's
+	// current roles can be retrieved from the SAMS API.
 	OnUserRolesUpdated func(ctx context.Context, data *UserRolesUpdatedData) error
+	// OnSessionInvalidated is called when a "SessionInvalidated" notification is
+	// received.
+	//
+	// It indicates that a user's session has been invalidated and the handler
+	// SHOULD take appropriate action to log the user out of the system.
+	OnSessionInvalidated func(ctx context.Context, data *SessionInvalidatedData) error
 }
 
 type ReceiveSettings = pubsub.ReceiveSettings
@@ -218,6 +225,15 @@ func (s *subscriber) handleReceive(ctx context.Context, name string, metadata js
 		}
 
 		return "handled", s.handlers.OnUserRolesUpdated(ctx, &data)
+	case nameSessionInvalidated:
+		if s.handlers.OnSessionInvalidated == nil {
+			return "skipped", nil
+		}
+		var data SessionInvalidatedData
+		if err := json.Unmarshal(metadata, &data); err != nil {
+			return "malformed_message", errors.Wrap(err, "unmarshal metadata")
+		}
+		return "handled", s.handlers.OnSessionInvalidated(ctx, &data)
 	}
 
 	// Unknown message type

notifications/v1/types.go

@@ -1,16 +1,18 @@
 package v1
 
 import (
-	"github.com/sourcegraph/sourcegraph-accounts-sdk-go/services"
 	"go.opentelemetry.io/otel"
+
+	"github.com/sourcegraph/sourcegraph-accounts-sdk-go/services"
 )
 
 // ⚠️ WARNING: These types MUST match the SAMS implementation, at
 // backend/internal/notification/types.go
 
 const (
-	nameUserDeleted      = "UserDeleted"
-	nameUserRolesUpdated = "UserRolesUpdated"
+	nameUserDeleted        = "UserDeleted"
+	nameUserRolesUpdated   = "UserRolesUpdated"
+	nameSessionInvalidated = "SessionInvalidated"
 )
 
 // UserDeletedData contains information of a "UserDeleted" notification.
@@ -23,8 +25,20 @@ type UserDeletedData struct {
 
 // UserRolesUpdatedData contains information of a "UserRolesUpdated" notification.
 type UserRolesUpdatedData struct {
-	AccountID string           `json:"account_id"`
-	Service   services.Service `json:"service"`
+	// AccountID is the SAMS external ID of the user whose roles have been updated.
+	AccountID string `json:"account_id"`
+	// Service is the service that the user's roles have been updated in.
+	Service services.Service `json:"service"`
+}
+
+// SessionInvalidatedData contains information of a "SessionInvalidated"
+// notification.
+type SessionInvalidatedData struct {
+	// AccountID is the SAMS external ID of the user whose session has been
+	// invalidated.
+	AccountID string `json:"account_id"`
+	// SessionID is the ID of the invalidated session.
+	SessionID string `json:"session_id"`
 }
 
 var tracer = otel.Tracer("sams.notifications.v1")