《游戏服务端架构·核心系统与契约》12.2 多游戏复用与租户隔离

// file: internal/tenantisolation/tenant.go
// tier: L1
// verify: go test ./internal/tenantisolation/

// Package tenantisolation binds every request to one (game, channel,
// environment) tuple and refuses reads or writes that cross that boundary.
package tenantisolation

import (
	"context"
	"errors"
	"fmt"
	"strings"
)

// Tenant is the isolation key shared by all platform services. Game alone is
// not enough: a staging write must not be visible in production, and two
// channels of the same game must not share player rows.
type Tenant struct {
	GameID  string
	Channel string
	Env     string
}

var (
	ErrIncompleteTenant = errors.New("tenantisolation: incomplete tenant")
	ErrBadSegment       = errors.New("tenantisolation: tenant segment contains a slash")
	ErrNoTenant         = errors.New("tenantisolation: tenant missing from context")
	ErrCrossTenant      = errors.New("tenantisolation: cross-tenant access denied")
	ErrBadKey           = errors.New("tenantisolation: key must not be empty or contain a slash")
	ErrBadQuota         = errors.New("tenantisolation: quota must have positive rate and burst >= 1")
	ErrBadCost          = errors.New("tenantisolation: cost must be positive")
)

// Validate rejects partially filled tenants. Callers should fail at the edge
// rather than write rows with an empty channel or environment.
func (t Tenant) Validate() error {
	if t.GameID == "" || t.Channel == "" || t.Env == "" {
		return ErrIncompleteTenant
	}
	for _, part := range []string{t.GameID, t.Channel, t.Env} {
		if strings.Contains(part, "/") {
			return ErrBadSegment
		}
	}
	return nil
}

// Key builds the storage key. Tenant fields always come first so a key from
// one tenant can never collide with a key from another.
func (t Tenant) Key(id string) (string, error) {
	if err := t.Validate(); err != nil {
		return "", err
	}
	if id == "" || strings.Contains(id, "/") {
		return "", ErrBadKey
	}
	return t.GameID + "/" + t.Channel + "/" + t.Env + "/" + id, nil
}

func (t Tenant) String() string {
	return t.GameID + "/" + t.Channel + "/" + t.Env
}

type tenantKey struct{}

// WithTenant stores the tenant in the request context. It refuses invalid
// tenants so a missing field cannot travel deeper into the stack.
func WithTenant(ctx context.Context, t Tenant) (context.Context, error) {
	if err := t.Validate(); err != nil {
		return ctx, err
	}
	return context.WithValue(ctx, tenantKey{}, t), nil
}

func FromContext(ctx context.Context) (Tenant, error) {
	t, ok := ctx.Value(tenantKey{}).(Tenant)
	if !ok {
		return Tenant{}, ErrNoTenant
	}
	return t, nil
}

// Authorize runs before a service touches a row. It compares the full tuple,
// not just GameID, because staging and production must not share data either.
func Authorize(actor, target Tenant) error {
	if err := actor.Validate(); err != nil {
		return err
	}
	if err := target.Validate(); err != nil {
		return err
	}
	if actor != target {
		return fmt.Errorf("%w: %s -> %s", ErrCrossTenant, actor, target)
	}
	return nil
}

// file: internal/tenantisolation/limiter.go
// tier: L1
// verify: go test ./internal/tenantisolation/
package tenantisolation

import (
	"sync"
	"time"
)

// Quota is a per-tenant token bucket. Rate is tokens per second; Burst is the
// maximum bucket size and therefore the largest single spike a tenant can
// create without waiting.
type Quota struct {
	Rate  float64
	Burst float64
}

// Limiter keeps one bucket per tenant key. A tenant that saturates its own
// bucket cannot consume another tenant's tokens.
type Limiter struct {
	mu       sync.Mutex
	now      func() time.Time
	defaultQ Quota
	buckets  map[string]*bucket
}

type bucket struct {
	tokens float64
	last   time.Time
	quota  Quota
}

func NewLimiter(defaultQ Quota) *Limiter {
	return &Limiter{
		now:      time.Now,
		defaultQ: defaultQ,
		buckets:  map[string]*bucket{},
	}
}

// SetClock replaces the clock. Tests use it to make refill deterministic.
func (l *Limiter) SetClock(now func() time.Time) {
	l.mu.Lock()
	defer l.mu.Unlock()
	l.now = now
}

// SetQuota overrides the default for one tenant, for example during a launch
// event that the platform agreed to absorb. The bucket starts full so the
// override takes effect immediately.
func (l *Limiter) SetQuota(t Tenant, q Quota) error {
	if err := t.Validate(); err != nil {
		return err
	}
	if q.Rate <= 0 || q.Burst < 1 {
		return ErrBadQuota
	}
	l.mu.Lock()
	defer l.mu.Unlock()
	l.buckets[t.String()] = &bucket{tokens: q.Burst, last: l.now(), quota: q}
	return nil
}

// Allow consumes cost tokens if the tenant has them. Refill is computed from
// elapsed time, so an idle tenant starts its next burst full without a
// background job and without scanning every other tenant.
func (l *Limiter) Allow(t Tenant, cost float64) (bool, error) {
	if err := t.Validate(); err != nil {
		return false, err
	}
	if cost <= 0 {
		return false, ErrBadCost
	}
	l.mu.Lock()
	defer l.mu.Unlock()
	key := t.String()
	b, ok := l.buckets[key]
	if !ok {
		b = &bucket{tokens: l.defaultQ.Burst, last: l.now(), quota: l.defaultQ}
		l.buckets[key] = b
	}
	l.refill(b)
	if b.tokens < cost {
		return false, nil
	}
	b.tokens -= cost
	return true, nil
}

// Remaining reports the tokens available right now without consuming any.
func (l *Limiter) Remaining(t Tenant) (float64, error) {
	if err := t.Validate(); err != nil {
		return 0, err
	}
	l.mu.Lock()
	defer l.mu.Unlock()
	b, ok := l.buckets[t.String()]
	if !ok {
		return l.defaultQ.Burst, nil
	}
	l.refill(b)
	return b.tokens, nil
}

func (l *Limiter) refill(b *bucket) {
	now := l.now()
	elapsed := now.Sub(b.last).Seconds()
	if elapsed <= 0 {
		return
	}
	b.tokens += elapsed * b.quota.Rate
	if b.tokens > b.quota.Burst {
		b.tokens = b.quota.Burst
	}
	b.last = now
}

$ cd .local/checks/gsarch-lab
$ gofmt -l internal/tenantisolation
$ go vet ./internal/tenantisolation/...
$ go test -count=1 ./internal/tenantisolation/...
ok  	gsarchlab/internal/tenantisolation