feat: game lobby service

2026-04-25 23:20:55 +02:00
parent 32dc29359a
commit 48b0056b49
336 changed files with 57074 additions and 1418 deletions
@@ -0,0 +1,188 @@
+// Package invite defines the invite record domain model, status machine,
+// and sentinel errors owned by Game Lobby Service for private-game
+// enrollment.
+package invite
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"galaxy/lobby/internal/domain/common"
+)
+
+// Invite stores one durable invite record owned by Game Lobby Service.
+// Invites are used exclusively by private games; public games use the
+// application flow instead.
+type Invite struct {
+	// InviteID identifies the record.
+	InviteID common.InviteID
+
+	// GameID identifies the game this invite belongs to.
+	GameID common.GameID
+
+	// InviterUserID stores the platform user id of the private-game owner
+	// who created the invite.
+	InviterUserID string
+
+	// InviteeUserID stores the platform user id of the invited user.
+	InviteeUserID string
+
+	// RaceName stores the invitee's chosen in-game name. It is empty until
+	// the invite transitions to redeemed.
+	RaceName string
+
+	// Status stores the current lifecycle state.
+	Status Status
+
+	// CreatedAt stores when the record was created.
+	CreatedAt time.Time
+
+	// ExpiresAt stores the business deadline after which the invite is no
+	// longer actionable. It equals enrollment_ends_at of the parent game
+	// at creation time.
+	ExpiresAt time.Time
+
+	// DecidedAt stores when the record transitioned out of created. It is
+	// nil while the invite is still created.
+	DecidedAt *time.Time
+}
+
+// NewInviteInput groups all fields required to create an invite record.
+type NewInviteInput struct {
+	// InviteID identifies the new record.
+	InviteID common.InviteID
+
+	// GameID identifies the game the invitee is being invited to.
+	GameID common.GameID
+
+	// InviterUserID stores the platform user id of the private-game owner.
+	InviterUserID string
+
+	// InviteeUserID stores the platform user id of the invited user.
+	InviteeUserID string
+
+	// Now stores the creation wall-clock used for CreatedAt.
+	Now time.Time
+
+	// ExpiresAt stores the business deadline propagated from the parent
+	// game's enrollment_ends_at.
+	ExpiresAt time.Time
+}
+
+// New validates input and returns a created Invite record. Validation
+// errors are returned verbatim so callers can surface them as
+// invalid_request.
+func New(input NewInviteInput) (Invite, error) {
+	if err := input.Validate(); err != nil {
+		return Invite{}, err
+	}
+
+	record := Invite{
+		InviteID:      input.InviteID,
+		GameID:        input.GameID,
+		InviterUserID: strings.TrimSpace(input.InviterUserID),
+		InviteeUserID: strings.TrimSpace(input.InviteeUserID),
+		Status:        StatusCreated,
+		CreatedAt:     input.Now.UTC(),
+		ExpiresAt:     input.ExpiresAt.UTC(),
+	}
+
+	if err := record.Validate(); err != nil {
+		return Invite{}, err
+	}
+
+	return record, nil
+}
+
+// Validate reports whether input satisfies the frozen invite-record
+// invariants required to construct a created record.
+func (input NewInviteInput) Validate() error {
+	if err := input.InviteID.Validate(); err != nil {
+		return fmt.Errorf("invite id: %w", err)
+	}
+	if err := input.GameID.Validate(); err != nil {
+		return fmt.Errorf("game id: %w", err)
+	}
+	if strings.TrimSpace(input.InviterUserID) == "" {
+		return fmt.Errorf("inviter user id must not be empty")
+	}
+	if strings.TrimSpace(input.InviteeUserID) == "" {
+		return fmt.Errorf("invitee user id must not be empty")
+	}
+	if strings.TrimSpace(input.InviterUserID) == strings.TrimSpace(input.InviteeUserID) {
+		return fmt.Errorf("inviter and invitee must not be the same user")
+	}
+	if input.Now.IsZero() {
+		return fmt.Errorf("now must not be zero")
+	}
+	if input.ExpiresAt.IsZero() {
+		return fmt.Errorf("expires at must not be zero")
+	}
+	if !input.ExpiresAt.After(input.Now) {
+		return fmt.Errorf("expires at must be after now")
+	}
+	return nil
+}
+
+// Validate reports whether record satisfies the full invariants.
+// Every marshal and unmarshal round-trip calls Validate to guarantee that
+// the Redis store never exposes malformed records.
+func (record Invite) Validate() error {
+	if err := record.InviteID.Validate(); err != nil {
+		return fmt.Errorf("invite id: %w", err)
+	}
+	if err := record.GameID.Validate(); err != nil {
+		return fmt.Errorf("game id: %w", err)
+	}
+	if strings.TrimSpace(record.InviterUserID) == "" {
+		return fmt.Errorf("inviter user id must not be empty")
+	}
+	if strings.TrimSpace(record.InviteeUserID) == "" {
+		return fmt.Errorf("invitee user id must not be empty")
+	}
+	if !record.Status.IsKnown() {
+		return fmt.Errorf("status %q is unsupported", record.Status)
+	}
+	if record.CreatedAt.IsZero() {
+		return fmt.Errorf("created at must not be zero")
+	}
+	if record.ExpiresAt.IsZero() {
+		return fmt.Errorf("expires at must not be zero")
+	}
+	if record.ExpiresAt.Before(record.CreatedAt) {
+		return fmt.Errorf("expires at must not be before created at")
+	}
+	switch record.Status {
+	case StatusCreated:
+		if record.DecidedAt != nil {
+			return fmt.Errorf("decided at must be nil for created invites")
+		}
+		if record.RaceName != "" {
+			return fmt.Errorf("race name must be empty for created invites")
+		}
+	case StatusRedeemed:
+		if strings.TrimSpace(record.RaceName) == "" {
+			return fmt.Errorf("race name must not be empty for redeemed invites")
+		}
+		if record.DecidedAt == nil {
+			return fmt.Errorf("decided at must not be nil for redeemed invites")
+		}
+	default:
+		if record.RaceName != "" {
+			return fmt.Errorf("race name must be empty for %q invites", record.Status)
+		}
+		if record.DecidedAt == nil {
+			return fmt.Errorf("decided at must not be nil for %q invites", record.Status)
+		}
+	}
+	if record.DecidedAt != nil {
+		if record.DecidedAt.IsZero() {
+			return fmt.Errorf("decided at must not be zero when present")
+		}
+		if record.DecidedAt.Before(record.CreatedAt) {
+			return fmt.Errorf("decided at must not be before created at")
+		}
+	}
+	return nil
+}