party

Documentation

Index

• Constants
• Variables
• type Config
  • func DefaultConfig() Config
• type JoinOutcome
• type JoinRequest
• type LeaveOutcome
• type MembershipChangeFn
• type PartyListEntry
• type PartyMember
• type PartySession
• type Presence
• type Registry
  • func NewRegistry() *Registry
  • func NewRegistryWithConfig(cfg Config) *Registry
  • func (r *Registry) Accept(partyID, leaderSessionID string, target Presence) (*PartySession, *PartyMember, error)
  • func (r *Registry) Close(partyID, leaderSessionID string) (*PartySession, error)
  • func (r *Registry) Count() int
  • func (r *Registry) Create(leaderID, username, sessionID string, open, hidden bool, maxSize int, ...) (*PartySession, error)
  • func (r *Registry) CreateParty(leaderID, username, sessionID string, open bool, maxSize int) (*PartySession, error)
  • func (r *Registry) GetParty(partyID string) (*PartySession, error)
  • func (r *Registry) Join(partyID, userID, username, sessionID string) (*JoinOutcome, error)
  • func (r *Registry) JoinParty(partyID, userID, username, sessionID string) (*PartySession, error)
  • func (r *Registry) JoinRequestList(partyID, leaderSessionID string) ([]*JoinRequest, error)
  • func (r *Registry) Leave(partyID, userID string) (*LeaveOutcome, error)
  • func (r *Registry) LeaveParty(partyID, userID string) (*PartySession, error)
  • func (r *Registry) LeaveSession(sessionID string) (*LeaveOutcome, error)
  • func (r *Registry) List(limit int, open *bool, showHidden bool, query, cursor string) ([]*PartyListEntry, string, error)
  • func (r *Registry) PartyIDForSession(sessionID string) (string, bool)
  • func (r *Registry) Promote(partyID, leaderSessionID string, target Presence) (*PartySession, *PartyMember, error)
  • func (r *Registry) Remove(partyID, leaderSessionID string, target Presence) (*RemoveOutcome, error)
  • func (r *Registry) SetMembershipChangeHook(fn MembershipChangeFn)
  • func (r *Registry) StopIdleSweep()
  • func (r *Registry) SweepIdle()
  • func (r *Registry) Update(partyID, leaderSessionID, label string, open, hidden bool) (*PartySession, error)
  • func (r *Registry) UpdateMemberProperties(partyID, userID string, properties map[string]interface{}) (*PartySession, error)
• type RemoveOutcome

Constants

const (
	LabelMaxBytes   = 2048
	AbsoluteMaxSize = 256
	DefaultMaxSize  = 4
)

Variables

var (
	ErrPartyNotFound        = errors.New("party not found")
	ErrNotLeader            = errors.New("operation allowed only for party leader")
	ErrPartyFull            = errors.New("party is full")
	ErrPartyClosed          = errors.New("party is closed")
	ErrMemberNotFound       = errors.New("member not found")
	ErrInvalidMaxSize       = errors.New("invalid max size (must be between 1 and 256)")
	ErrAlreadyMember        = errors.New("already a party member")
	ErrJoinRequestDuplicate = errors.New("join request already pending")
	ErrJoinRequestsFull     = errors.New("join request list is full")
	ErrNotJoinRequest       = errors.New("presence is not a pending join request")
	ErrRemoveSelf           = errors.New("cannot remove self from party")
	ErrAlreadyInParty       = errors.New("user already in another party")
	ErrInvalidLabel         = errors.New("invalid party label")
	ErrHiddenNonEmptyLabel  = errors.New("party is hidden and label is not empty")
	ErrPartyClosedForList   = errors.New("party closed")
)

Types

type Config

type Config struct {
	Node            string
	SingleParty     bool
	DefaultMaxSize  int
	AbsoluteMaxSize int
	IdleCheckMs     int
}

Config controls registry behaviour.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns reference-aligned defaults.

type JoinOutcome

type JoinOutcome struct {
	Party  *PartySession
	Joined bool // true if member; false if join request queued
}

JoinOutcome is returned from Join.

type JoinRequest

type JoinRequest struct {
	UserID    string    `json:"user_id"`
	Username  string    `json:"username"`
	SessionID string    `json:"session_id"`
	Requested time.Time `json:"requested"`
}

JoinRequest is a pending closed-party join request.

type LeaveOutcome

type LeaveOutcome struct {
	Party          *PartySession
	PromotedLeader *PartyMember
	Dissolved      bool
	WasMember      bool
}

LeaveOutcome is returned from Leave / LeaveSession.

type MembershipChangeFn

type MembershipChangeFn func(partyID string)

MembershipChangeFn is invoked when party membership changes (cancel MM tickets).

type PartyListEntry

type PartyListEntry struct {
	ID      string `json:"id"`
	Open    bool   `json:"open"`
	Hidden  bool   `json:"hidden"`
	MaxSize int    `json:"max_size"`
	Label   string `json:"label"`
}

PartyListEntry is a discoverable party row for ListParties.

type PartyMember

type PartyMember struct {
	UserID     string                 `json:"user_id"`
	Username   string                 `json:"username"`
	SessionID  string                 `json:"session_id"`
	JoinedAt   time.Time              `json:"joined_at"`
	Properties map[string]interface{} `json:"properties"`
}

PartyMember represents a player in an active party.

type PartySession

type PartySession struct {
	PartyID      string                  `json:"party_id"`
	LeaderID     string                  `json:"leader_id"`
	Open         bool                    `json:"open"`
	Hidden       bool                    `json:"hidden"`
	MaxSize      int                     `json:"max_size"`
	Label        string                  `json:"label"`
	Members      map[string]*PartyMember `json:"members"`       // key: userID
	JoinRequests map[string]*JoinRequest `json:"join_requests"` // key: userID
	Node         string                  `json:"node"`
	CreateTime   time.Time               `json:"create_time"`
	LastActive   time.Time               `json:"last_active"`
	// contains filtered or unexported fields
}

PartySession represents a transient, in-memory party group.

type Presence

type Presence struct {
	UserID    string `json:"user_id"`
	Username  string `json:"username"`
	SessionID string `json:"session_id"`
}

Presence identifies a user/session for leader ops.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry manages thread-safe memory maps of active parties.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates a party registry with default config.

func NewRegistryWithConfig

func NewRegistryWithConfig(cfg Config) *Registry

NewRegistryWithConfig creates a registry with the given config.

func (*Registry) Accept

func (r *Registry) Accept(partyID, leaderSessionID string, target Presence) (*PartySession, *PartyMember, error)

Accept accepts a pending join request.

func (*Registry) Close

func (r *Registry) Close(partyID, leaderSessionID string) (*PartySession, error)

Close dissolves the party (leader only).

func (*Registry) Count

func (r *Registry) Count() int

Count returns active party count.

func (*Registry) Create

func (r *Registry) Create(leaderID, username, sessionID string, open, hidden bool, maxSize int, label string) (*PartySession, error)

Create creates a new party; creator is leader. Enforces single-party when configured.

func (*Registry) CreateParty

func (r *Registry) CreateParty(leaderID, username, sessionID string, open bool, maxSize int) (*PartySession, error)

CreateParty is an alias matching older call sites (open parties, default label).

func (*Registry) GetParty

func (r *Registry) GetParty(partyID string) (*PartySession, error)

GetParty retrieves a party by ID (cloned snapshot).

func (*Registry) Join

func (r *Registry) Join(partyID, userID, username, sessionID string) (*JoinOutcome, error)

JoinOutcome Join adds a member (open) or queues a join request (closed).

func (*Registry) JoinParty

func (r *Registry) JoinParty(partyID, userID, username, sessionID string) (*PartySession, error)

JoinParty wraps Join for older call sites that expect immediate membership (open or already accepted).

func (*Registry) JoinRequestList

func (r *Registry) JoinRequestList(partyID, leaderSessionID string) ([]*JoinRequest, error)

JoinRequestList returns pending join requests (leader only).

func (*Registry) Leave

func (r *Registry) Leave(partyID, userID string) (*LeaveOutcome, error)

Leave removes a user from the party.

func (*Registry) LeaveParty

func (r *Registry) LeaveParty(partyID, userID string) (*PartySession, error)

LeaveParty wraps Leave for older call sites.

func (*Registry) LeaveSession

func (r *Registry) LeaveSession(sessionID string) (*LeaveOutcome, error)

LeaveSession removes the session from whatever party it is in.

func (*Registry) List

func (r *Registry) List(limit int, open *bool, showHidden bool, query, cursor string) ([]*PartyListEntry, string, error)

List returns discoverable parties (in-memory filter + cursor).

func (*Registry) PartyIDForSession

func (r *Registry) PartyIDForSession(sessionID string) (string, bool)

PartyIDForSession returns the party ID for a session, if any.

func (*Registry) Promote

func (r *Registry) Promote(partyID, leaderSessionID string, target Presence) (*PartySession, *PartyMember, error)

Promote transfers leadership.

func (*Registry) Remove

func (r *Registry) Remove(partyID, leaderSessionID string, target Presence) (*RemoveOutcome, error)

Remove kicks a member or rejects a join request.

func (*Registry) SetMembershipChangeHook

func (r *Registry) SetMembershipChangeHook(fn MembershipChangeFn)

SetMembershipChangeHook registers a callback for membership changes.

func (*Registry) StopIdleSweep

func (r *Registry) StopIdleSweep()

StopIdleSweep stops the idle ticker.

func (*Registry) SweepIdle

func (r *Registry) SweepIdle()

SweepIdle closes parties with no members (safety) or no activity since last check and empty stream.

func (*Registry) Update

func (r *Registry) Update(partyID, leaderSessionID, label string, open, hidden bool) (*PartySession, error)

Update updates open/hidden/label (leader only).

func (*Registry) UpdateMemberProperties

func (r *Registry) UpdateMemberProperties(partyID, userID string, properties map[string]interface{}) (*PartySession, error)

UpdateMemberProperties updates custom variables for a party member.

type RemoveOutcome

type RemoveOutcome struct {
	Party           *PartySession
	Kicked          *PartyMember
	RejectedRequest bool
}

RemoveOutcome is returned from Remove.