Documentation > Resource Contracts

Resource Contracts

Resource Contracts bridge the gap between service goals and resource allocation. They allow services to declare their resource requirements and quality-of-service expectations without directly implementing bidding logic.

🎯 Core Principle

Resource contracts separate what you need from how you pay for it. Goals define success criteria, contracts define resource commitments.

Why Resource Contracts?

Traditional systems mix business logic with resource concerns:

❌ Without Resource Contracts

Services must handle both business logic AND resource economics, creating tight coupling.

✅ With Resource Contracts

Services focus on business logic while contracts handle resource economics declaratively.

Key Benefits

  • Separation of Concerns: Business logic vs. resource economics
  • Future-Proofing: Contracts work with current FCFS and future bidding systems
  • Composability: Contracts can be combined and inherited
  • Testability: Contracts can be mocked for testing
  • Observability: Clear resource expectations and actual usage

Contract Structure

Resource contracts are attached to goals and define resource expectations:

Basic Contract

goals:
  - name: apiResponseTime
    metric: latency
    target: "< 200ms"
    resourceContract:
      priority: high
      computeUnits: 100
      maxWaitTime: "5s"

Advanced Contract

goals:
  - name: criticalTransaction
    metric: successRate
    target: "> 99.9%"
    resourceContract:
      priority: critical
      computeUnits: 500
      maxWaitTime: "1s"
      futuresEnabled: true
      fallbackBehavior: retry
      costCeiling: 10

Contract Fields

Field Type Default Description
priority string normal Priority level: low, normal, high, critical
computeUnits integer 100 Estimated compute units needed (affects queue positioning)
maxWaitTime duration 30s Maximum acceptable queue wait time
futuresEnabled boolean false Allow futures-based resource reservation
fallbackBehavior string queue What to do when resources unavailable: queue, retry, degrade, fail
costCeiling integer unlimited Maximum credits willing to spend (future bidding)

Priority Levels

Contracts use priority levels to influence resource allocation:

Priority Mapping

  • Critical: System stability, payment processing, security
  • High: User-facing APIs, real-time features
  • Normal: Background processing, analytics
  • Low: Batch jobs, cleanup tasks

Fallback Behaviors

When resource contracts cannot be fulfilled, services can specify fallback behavior:

Queue (Default)

Wait in queue until resources become available within maxWaitTime.

Retry

Retry the operation with exponential backoff, potentially with reduced resource requirements.

Degrade

Execute with reduced functionality or quality (e.g., lower resolution, cached results).

Fail

Return an error immediately without queuing.

Contract Composition

Services can define contracts at multiple levels:

Service-Level Contracts

services:
  - name: api
    resourceContract:  # Applies to all goals
      priority: high
      maxWaitTime: "10s"
    goals:
      - name: responseTime
        metric: latency
        target: "< 200ms"
        resourceContract:  # Overrides service-level
          priority: critical
          maxWaitTime: "2s"

Bundle-Level Contracts

bundle:
  name: ecommerce
  resourceContract:
    priority: normal
    futuresEnabled: true

services:
  - name: payment
    resourceContract:
      priority: critical  # Overrides bundle default

Contract Lifecycle

Contract Evaluation Flow

1. Request
2. Evaluate
3. Allocate
4. Monitor
5. Complete
Service makes request with contract
Check available resources vs. contract
Allocate resources or queue
Track actual vs. estimated usage
Update contract performance metrics

Future Integration

Resource contracts are designed to work with future bidding systems:

🔮 Bidding Integration

When bidding activates, contracts will automatically participate using their priority and cost ceiling settings.

Automatic Bidding

resourceContract:
  priority: high
  costCeiling: 5
  autoBid: true  # Automatically bid up to costCeiling

Futures Contracts

resourceContract:
  futuresEnabled: true
  futuresHorizon: "1h"  # Reserve resources 1 hour ahead
  futuresBudget: 20     # Credits allocated for futures

Best Practices

🎯 Resource Contract Guidelines

  • Be Specific: Estimate compute units based on actual usage patterns
  • Set Realistic Limits: Use appropriate maxWaitTime for user experience
  • Plan for Failure: Always specify meaningful fallback behavior
  • Monitor Usage: Track actual vs. estimated resource consumption
  • Start Conservative: Begin with lower priorities and increase as needed
  • Use Composition: Leverage bundle and service-level defaults

Related Concepts

Goals & Metrics
How resource contracts attach to goals
Services
Where resource contracts are defined
Bidding System
How contracts will integrate with future bidding