cloud

package
v1.17.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 25, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package cloud provides a multi-tenant managed inference service for Zerfoo.

It wraps the serve.Server with tenant isolation, token-based billing, rate limiting, and health checking for cloud deployments.

Stability: alpha

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AuditAction 

type AuditAction string

AuditAction identifies the type of API operation being logged. 

const (
	AuditActionInference AuditAction = "inference"
	AuditActionCreate    AuditAction = "create"
	AuditActionUpdate    AuditAction = "update"
	AuditActionDelete    AuditAction = "delete"
	AuditActionList      AuditAction = "list"
	AuditActionAuth      AuditAction = "auth"
)

type AuditEntry 

type AuditEntry struct {
	Timestamp  time.Time   `json:"timestamp"`
	TenantID   string      `json:"tenant_id"`
	Action     AuditAction `json:"action"`
	Result     AuditResult `json:"result"`
	Resource   string      `json:"resource"`
	StatusCode int         `json:"status_code"`
	Method     string      `json:"method"`
	Path       string      `json:"path"`
	RemoteAddr string      `json:"remote_addr"`
}

AuditEntry records a single auditable event for SOC 2 compliance. Sensitive data (API keys, request bodies) is never stored.

type AuditLogger 

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

AuditLogger records API requests for SOC 2 compliance. It deliberately omits sensitive fields (API keys, request/response bodies).

func NewAuditLogger 

func NewAuditLogger(store AuditStore) *AuditLogger

NewAuditLogger creates an AuditLogger backed by the given store.

func (*AuditLogger) Log 

func (a *AuditLogger) Log(entry AuditEntry) error

Log records an audit entry.

func (*AuditLogger) Query 

func (a *AuditLogger) Query(tenantID string, from, to time.Time) ([]AuditEntry, error)

Query returns audit entries for a tenant within the given time range.

type AuditResult 

type AuditResult string

AuditResult records the outcome of an API request. 

const (
	AuditResultSuccess      AuditResult = "success"
	AuditResultDenied       AuditResult = "denied"
	AuditResultRateLimited  AuditResult = "rate_limited"
	AuditResultError        AuditResult = "error"
	AuditResultUnauthorized AuditResult = "unauthorized"
)

type AuditStore 

type AuditStore interface {
	// Append persists an audit entry.
	Append(entry AuditEntry) error

	// Query returns audit entries for a tenant within the given time range.
	Query(tenantID string, from, to time.Time) ([]AuditEntry, error)
}

AuditStore is the persistence interface for audit entries.

type BillingRecord 

type BillingRecord struct {
	TenantID     string    `json:"tenant_id"`
	InputTokens  int       `json:"input_tokens"`
	OutputTokens int       `json:"output_tokens"`
	Timestamp    time.Time `json:"timestamp"`
}

BillingRecord captures token usage for a single inference request.

type BillingStore 

type BillingStore interface {
	// Store persists a billing record.
	Store(record BillingRecord) error

	// Query returns all billing records for a tenant within the given time range.
	Query(tenantID string, from, to time.Time) ([]BillingRecord, error)
}

BillingStore is the persistence interface for billing records.

type CloudServer 

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

CloudServer wraps an HTTP handler with multi-tenant isolation, token billing, rate limiting, and health checking for cloud deployments.

func NewCloudServer 

func NewCloudServer(handler http.Handler, tenants *TenantManager, meter *TokenMeter) *CloudServer

NewCloudServer creates a CloudServer that routes authenticated requests to the given handler through tenant isolation middleware.

func (*CloudServer) Handler 

func (cs *CloudServer) Handler() http.Handler

Handler returns the root HTTP handler with all middleware applied.

func (*CloudServer) Meter 

func (cs *CloudServer) Meter() *TokenMeter

Meter returns the TokenMeter for external billing queries.

func (*CloudServer) SetHealthy 

func (cs *CloudServer) SetHealthy(healthy bool)

SetHealthy sets the health status of the cloud server.

func (*CloudServer) Tenants 

func (cs *CloudServer) Tenants() *TenantManager

Tenants returns the TenantManager for external CRUD operations.

type MemoryAuditStore 

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

MemoryAuditStore is an in-memory AuditStore for testing and development.

func NewMemoryAuditStore 

func NewMemoryAuditStore() *MemoryAuditStore

NewMemoryAuditStore creates a new in-memory audit store.

func (*MemoryAuditStore) All 

func (s *MemoryAuditStore) All() []AuditEntry

All returns a copy of all stored entries.

func (*MemoryAuditStore) Append 

func (s *MemoryAuditStore) Append(entry AuditEntry) error

Append appends an entry to the in-memory store.

func (*MemoryAuditStore) Query 

func (s *MemoryAuditStore) Query(tenantID string, from, to time.Time) ([]AuditEntry, error)

Query returns entries matching the tenant and time range.

type MemoryBillingStore 

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

MemoryBillingStore is an in-memory BillingStore for testing and development.

func NewMemoryBillingStore 

func NewMemoryBillingStore() *MemoryBillingStore

NewMemoryBillingStore creates a new in-memory billing store.

func (*MemoryBillingStore) All 

func (s *MemoryBillingStore) All() []BillingRecord

All returns a copy of all stored records.

func (*MemoryBillingStore) Query 

func (s *MemoryBillingStore) Query(tenantID string, from, to time.Time) ([]BillingRecord, error)

Query returns records matching the tenant and time range.

func (*MemoryBillingStore) Store 

func (s *MemoryBillingStore) Store(record BillingRecord) error

Store appends a record to the in-memory store.

type SAMLMetadata 

type SAMLMetadata struct {
	EntityID        string `json:"entity_id"`
	SignOnURL       string `json:"sign_on_url"`
	Certificate     string `json:"certificate"`
	NameIDFormat    string `json:"name_id_format,omitempty"`
	WantAuthnSigned bool   `json:"want_authn_signed"`
}

SAMLMetadata holds identity provider configuration parsed from SAML 2.0 metadata XML.

func ParseSAMLMetadata 

func ParseSAMLMetadata(data []byte) (*SAMLMetadata, error)

ParseSAMLMetadata parses SAML 2.0 IdP metadata XML into a SAMLMetadata struct.

type SAMLProvider 

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

SAMLProvider implements SSOProvider for SAML 2.0.

func NewSAMLProvider 

func NewSAMLProvider(metadata *SAMLMetadata, tenantID string) *SAMLProvider

NewSAMLProvider creates a SAML 2.0 SSO provider from parsed metadata, bound to a specific tenant.

func (*SAMLProvider) EntityID 

func (p *SAMLProvider) EntityID() string

EntityID returns the identity provider's entity ID.

func (*SAMLProvider) ValidateAssertion 

func (p *SAMLProvider) ValidateAssertion(assertion []byte) (*SSOIdentity, error)

ValidateAssertion parses and validates a SAML 2.0 assertion, including XXE protection, XML digital signature verification, NotBefore clock skew tolerance, and assertion replay prevention.

type SSOIdentity 

type SSOIdentity struct {
	Subject    string            `json:"subject"`
	TenantID   string            `json:"tenant_id"`
	Email      string            `json:"email,omitempty"`
	Attributes map[string]string `json:"attributes,omitempty"`
	ExpiresAt  time.Time         `json:"expires_at"`
}

SSOIdentity represents an authenticated user from an SSO provider.

type SSOProvider 

type SSOProvider interface {
	// EntityID returns the identity provider's entity ID.
	EntityID() string

	// ValidateAssertion validates an assertion and returns the authenticated identity.
	ValidateAssertion(assertion []byte) (*SSOIdentity, error)
}

SSOProvider defines the interface for SSO authentication. Implementations handle protocol-specific details (SAML 2.0, OIDC, etc.).

type Tenant 

type Tenant struct {
	ID string
	// contains filtered or unexported fields
}

Tenant represents a registered cloud tenant with runtime rate-limit state. Always accessed via pointer; must not be copied.

func (*Tenant) AllowRequest 

func (t *Tenant) AllowRequest() bool

AllowRequest checks whether the tenant can make another request this minute. Returns true and increments the counter if allowed.

func (*Tenant) Config 

func (t *Tenant) Config() TenantConfig

Config returns a copyable snapshot of the tenant's configuration. The APIKey field is redacted to prevent accidental credential leakage.

func (*Tenant) ConsumeTokens 

func (t *Tenant) ConsumeTokens(n int64) bool

ConsumeTokens attempts to consume n tokens from the per-minute budget. Returns true if the tokens were consumed.

func (*Tenant) DeductTokens added in v1.16.0 

func (t *Tenant) DeductTokens(n int64)

DeductTokens unconditionally adds n tokens to the consumed count without checking the budget. This is used to charge excess usage when actual token generation exceeds the pre-authorized estimate (e.g. max_tokens=1 but the model produced more tokens). Unlike ConsumeTokens, it never fails.

func (*Tenant) RefundTokens added in v1.12.0 

func (t *Tenant) RefundTokens(n int64)

RefundTokens returns n tokens to the per-minute budget, used to reconcile pre-authorized estimates with actual usage after inference completes.

type TenantConfig 

type TenantConfig struct {
	ID          string `json:"id"`
	APIKey      string `json:"api_key"`
	RateLimit   int64  `json:"rate_limit"`   // max requests per minute
	TokenBudget int64  `json:"token_budget"` // max tokens per minute
}

TenantConfig is the input for creating or describing a tenant. It contains no atomic fields and is safe to copy.

type TenantManager 

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

TenantManager provides CRUD operations on tenants, keyed by both tenant ID and API key for O(1) lookups in either direction.

func NewTenantManager 

func NewTenantManager() *TenantManager

NewTenantManager creates a new empty TenantManager.

func (*TenantManager) Create 

func (m *TenantManager) Create(cfg TenantConfig) error

Create registers a new tenant. The tenant ID and API key must be unique.

func (*TenantManager) Delete 

func (m *TenantManager) Delete(id string) error

Delete removes a tenant by ID.

func (*TenantManager) Get 

func (m *TenantManager) Get(id string) (*Tenant, error)

Get retrieves a tenant by ID.

func (*TenantManager) GetByAPIKey 

func (m *TenantManager) GetByAPIKey(apiKey string) (*Tenant, error)

GetByAPIKey retrieves a tenant by API key. The input key is hashed with SHA-256 for O(1) map lookup, then verified with constant-time comparison on the hashes to prevent timing side-channel attacks.

func (*TenantManager) List 

func (m *TenantManager) List() []TenantConfig

List returns a copyable snapshot of all tenant configurations.

func (*TenantManager) Update 

func (m *TenantManager) Update(id string, rateLimit, tokenBudget int64) error

Update modifies a tenant's rate limits and token budget.

type TokenMeter 

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

TokenMeter tracks input and output token usage per tenant and emits billing records to a BillingStore.

func NewTokenMeter 

func NewTokenMeter(store BillingStore) *TokenMeter

NewTokenMeter creates a TokenMeter backed by the given BillingStore.

func (*TokenMeter) Query 

func (m *TokenMeter) Query(tenantID string, from, to time.Time) ([]BillingRecord, error)

Query returns billing records for a tenant within the given time range.

func (*TokenMeter) Record 

func (m *TokenMeter) Record(tenantID string, inputTokens, outputTokens int) error

Record records token usage for a tenant and persists a BillingRecord.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.