《游戏服务端架构·平台化与架构治理》1.2 内部开发者平台

// file: internal/idpportal/portal.go
// tier: L1
// verify: go test ./internal/idpportal/
package idpportal

import (
	"fmt"
	"strings"
	"sync"
)

// Quota is the pool a portal may hand out, not a suggestion. Usage is charged
// when an environment becomes ready, so failed attempts do not consume it.
type Quota struct {
	MaxCPU      int
	MaxMemoryGB int
	MaxEnvs     int
}

type Usage struct {
	CPU      int
	MemoryGB int
	Envs     int
}

func (q Quota) Validate() error {
	if q.MaxCPU <= 0 || q.MaxMemoryGB <= 0 || q.MaxEnvs <= 0 {
		return fmt.Errorf("%w: quota limits must be positive", ErrInvalid)
	}
	return nil
}

func (q Quota) Check(r Request, used Usage) error {
	if used.Envs+1 > q.MaxEnvs {
		return fmt.Errorf("%w: environments %d+1 > %d", ErrQuota, used.Envs, q.MaxEnvs)
	}
	if used.CPU+r.CPU > q.MaxCPU {
		return fmt.Errorf("%w: cpu %d+%d > %d", ErrQuota, used.CPU, r.CPU, q.MaxCPU)
	}
	if used.MemoryGB+r.MemoryGB > q.MaxMemoryGB {
		return fmt.Errorf("%w: memory %d+%d > %d", ErrQuota, used.MemoryGB, r.MemoryGB, q.MaxMemoryGB)
	}
	return nil
}

// Portal owns the state transitions. Callers may read requests but cannot
// assign a state; this keeps the API and the UI from drifting apart.
type Portal struct {
	mu       sync.Mutex
	quota    Quota
	requests map[string]Request
	keys     map[string]string
	usage    Usage
}

func New(q Quota) (*Portal, error) {
	if err := q.Validate(); err != nil {
		return nil, err
	}
	return &Portal{quota: q, requests: map[string]Request{}, keys: map[string]string{}}, nil
}

func (p *Portal) Usage() Usage {
	p.mu.Lock()
	defer p.mu.Unlock()
	return p.usage
}

func (p *Portal) Get(id string) (Request, error) {
	p.mu.Lock()
	defer p.mu.Unlock()
	r, ok := p.requests[id]
	if !ok {
		return Request{}, fmt.Errorf("%w: %s", ErrNotFound, id)
	}
	return r, nil
}

// Submit is idempotent per key. Replaying the same intent returns the stored
// request with created=false; reusing a key for a different intent fails
// loudly instead of silently creating a second environment.
func (p *Portal) Submit(key string, r Request) (Request, bool, error) {
	if strings.TrimSpace(key) == "" {
		return Request{}, false, fmt.Errorf("%w: idempotency key is empty", ErrInvalid)
	}
	if err := r.Validate(); err != nil {
		return Request{}, false, err
	}
	p.mu.Lock()
	defer p.mu.Unlock()

	if id, ok := p.keys[key]; ok {
		stored := p.requests[id]
		if stored.fingerprint() != r.fingerprint() {
			return Request{}, false, fmt.Errorf("%w: key %s", ErrKeyReuse, key)
		}
		return stored, false, nil
	}
	if _, ok := p.requests[r.ID]; ok {
		return Request{}, false, fmt.Errorf("%w: %s", ErrDuplicate, r.ID)
	}
	if err := p.quota.Check(r, p.usage); err != nil {
		return Request{}, false, err
	}
	r.State = StateRequested
	p.requests[r.ID] = r
	p.keys[key] = r.ID
	return r, true, nil
}

// Decide re-checks quota because the pool may have shrunk since submission.
// The golden path is auto-approved; the exception path needs a named approver.
func (p *Portal) Decide(id, approver string) (Request, error) {
	p.mu.Lock()
	defer p.mu.Unlock()

	r, ok := p.requests[id]
	if !ok {
		return Request{}, fmt.Errorf("%w: %s", ErrNotFound, id)
	}
	if err := CanTransition(r.State, StateApproved); err != nil {
		return r, err
	}
	if r.Path == ExceptionPath && strings.TrimSpace(approver) == "" {
		return r, fmt.Errorf("%w: %s", ErrApproval, id)
	}
	if r.Path == GoldenPath && strings.TrimSpace(approver) == "" {
		approver = "auto:golden-path"
	}
	if err := p.quota.Check(r, p.usage); err != nil {
		return r, err
	}
	r.State = StateApproved
	r.Approver = approver
	p.requests[id] = r
	return r, nil
}

func (p *Portal) Reject(id, reason string) (Request, error) {
	return p.move(id, StateRejected, func(r *Request) error {
		r.Reason = reason
		return nil
	})
}

func (p *Portal) Start(id string) (Request, error) {
	return p.move(id, StateProvisioning, nil)
}

// Finish is the only place usage is charged. A failed provisioning attempt
// leaves the pool untouched, so retries cannot leak capacity.
func (p *Portal) Finish(id string, success bool) (Request, error) {
	to := StateReady
	if !success {
		to = StateFailed
	}
	return p.move(id, to, func(r *Request) error {
		if to == StateReady {
			p.usage.CPU += r.CPU
			p.usage.MemoryGB += r.MemoryGB
			p.usage.Envs++
		}
		return nil
	})
}

func (p *Portal) move(id string, to State, before func(*Request) error) (Request, error) {
	p.mu.Lock()
	defer p.mu.Unlock()

	r, ok := p.requests[id]
	if !ok {
		return Request{}, fmt.Errorf("%w: %s", ErrNotFound, id)
	}
	if err := CanTransition(r.State, to); err != nil {
		return r, err
	}
	if before != nil {
		if err := before(&r); err != nil {
			return r, err
		}
	}
	r.State = to
	p.requests[id] = r
	return r, nil
}