《游戏服务端编程实践》4.1.1 账号、角色、租户与设备

player(player_id PK, account_id, region_id, name, level, ...)

// file: ch04/identity/model.go
// tier: L1
// verify: go test ./ch04/identity/

package identity

import (
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"sort"
	"time"
)

// AccountID identifies an account across tenants and regions.
type AccountID uint64

// PlayerID identifies a character inside one region. It is never used as an
// account ID: the two ID spaces are allocated independently.
type PlayerID uint64

// TenantID is a publisher, channel or operating boundary.
type TenantID string

// DeviceID is an installation instance, not a person.
type DeviceID string

var (
	ErrAccountNotFound = errors.New("identity: account not found")
	ErrDeviceBound     = errors.New("identity: device already bound to another account")
	ErrDeviceNotFound  = errors.New("identity: device not bound to account")
	ErrTenantMismatch  = errors.New("identity: account and device belong to different tenants")
)

// Device is a weak identity. FingerprintHash is a one-way hash; the raw
// fingerprint must never be persisted or used as a login credential.
type Device struct {
	ID              DeviceID
	Tenant          TenantID
	Platform        string
	FingerprintHash string
	BoundAt         time.Time
	LastSeenAt      time.Time
}

// PlayerRef is the identity-layer view of a character. Level, inventory and
// position stay in the region that owns the character.
type PlayerRef struct {
	ID        PlayerID
	AccountID AccountID
	Tenant    TenantID
	Region    string
	Name      string
}

// Account groups identities that survive device and region changes.
type Account struct {
	ID        AccountID
	Tenant    TenantID
	CreatedAt time.Time

	devices map[DeviceID]Device
	players map[PlayerID]struct{}
}

// Registry is an in-memory reference implementation of the identity rules.
// A production implementation replaces the maps with a transactional store.
type Registry struct {
	accounts    map[AccountID]*Account
	devices     map[DeviceID]AccountID
	players     map[PlayerID]*PlayerRef
	nextAccount AccountID
	nextPlayer  PlayerID
}

func NewRegistry() *Registry {
	return &Registry{
		accounts: make(map[AccountID]*Account),
		devices:  make(map[DeviceID]AccountID),
		players:  make(map[PlayerID]*PlayerRef),
	}
}

// NewAccount allocates a global account ID. IDs are opaque and never reused.
func (r *Registry) NewAccount(tenant TenantID, now time.Time) *Account {
	r.nextAccount++
	a := &Account{
		ID:        r.nextAccount,
		Tenant:    tenant,
		CreatedAt: now.UTC(),
		devices:   make(map[DeviceID]Device),
		players:   make(map[PlayerID]struct{}),
	}
	r.accounts[a.ID] = a
	return a
}

// NewPlayer allocates a region-scoped player ID for an existing account.
func (r *Registry) NewPlayer(accountID AccountID, region, name string) (PlayerRef, error) {
	a, ok := r.accounts[accountID]
	if !ok {
		return PlayerRef{}, ErrAccountNotFound
	}
	r.nextPlayer++
	p := &PlayerRef{
		ID:        r.nextPlayer,
		AccountID: accountID,
		Tenant:    a.Tenant,
		Region:    region,
		Name:      name,
	}
	r.players[p.ID] = p
	a.players[p.ID] = struct{}{}
	return *p, nil
}

// BindDevice attaches an installation to an account. Repeating the same
// binding is idempotent; moving a device to another account is rejected.
func (r *Registry) BindDevice(accountID AccountID, dev Device, now time.Time) error {
	a, ok := r.accounts[accountID]
	if !ok {
		return ErrAccountNotFound
	}
	if dev.Tenant != a.Tenant {
		return ErrTenantMismatch
	}
	if owner, ok := r.devices[dev.ID]; ok {
		if owner != accountID {
			return ErrDeviceBound
		}
		cur := a.devices[dev.ID]
		cur.LastSeenAt = now.UTC()
		a.devices[dev.ID] = cur
		return nil
	}
	dev.BoundAt = now.UTC()
	dev.LastSeenAt = now.UTC()
	a.devices[dev.ID] = dev
	r.devices[dev.ID] = accountID
	return nil
}

// UnbindDevice removes one installation. Characters and the account survive.
func (r *Registry) UnbindDevice(accountID AccountID, deviceID DeviceID) error {
	a, ok := r.accounts[accountID]
	if !ok {
		return ErrAccountNotFound
	}
	if _, ok := a.devices[deviceID]; !ok {
		return ErrDeviceNotFound
	}
	delete(a.devices, deviceID)
	if owner, ok := r.devices[deviceID]; ok && owner == accountID {
		delete(r.devices, deviceID)
	}
	return nil
}

// PlayersOf returns a stable snapshot of the account's characters.
func (r *Registry) PlayersOf(accountID AccountID) ([]PlayerRef, error) {
	a, ok := r.accounts[accountID]
	if !ok {
		return nil, ErrAccountNotFound
	}
	out := make([]PlayerRef, 0, len(a.players))
	for id := range a.players {
		if p, ok := r.players[id]; ok {
			out = append(out, *p)
		}
	}
	sort.Slice(out, func(i, j int) bool { return out[i].ID < out[j].ID })
	return out, nil
}

// HashFingerprint produces the only form of a device fingerprint that may be
// persisted. A fingerprint is a hint, never a login credential.
func HashFingerprint(raw string) string {
	sum := sha256.Sum256([]byte("gsp/device/v1\x00" + raw))
	return hex.EncodeToString(sum[:])
}