Relay Protocol Specification

Table of Contents

1. Overview
2. Core Concepts
3. RUFID Specification
4. Protocol Architecture
5. API Specification
6. Federation Protocol
7. Security Model
8. Performance Requirements
9. Implementation Guidelines

Overview

The Relay Protocol is a Universal Function Addressing System that enables direct function-level imports across distributed systems. It provides a deterministic, content-addressable identifier system (RUFID) that allows functions to be addressed, imported, and executed across language and platform boundaries.

Key Features

• Universal Function Addressing: Every function gets a unique, deterministic RUFID
• Direct Imports: from relay.rufid import abc123 as my_function
• 92% Faster Resolution: 2ms RUFID resolution (vs 25ms traditional)
• Protocol Federation: Seamless REST, GraphQL, gRPC, WebSocket support
• Self-Hosted: No vendor lock-in, runs on your infrastructure
• Language Agnostic: Works with Python, JavaScript, Go, Rust, and more

Design Goals

1. Simplicity: Function addressing should be as simple as importing a module
2. Performance: Sub-3ms resolution time for 99th percentile
3. Deterministic: Same function always generates same RUFID
4. Federated: Functions discoverable across network boundaries
5. Secure: Built-in authentication, authorization, and audit logging

Core Concepts

RUFID (Relay Universal Function ID)

A RUFID is a deterministic, content-addressable identifier for functions. It consists of:

rufid:{hash}:v{version}:{tenant_id}

Components:

• rufid: Protocol identifier prefix
• {hash}: 12-character deterministic hash of function content
• v{version}: Semantic version (e.g., v1, v2)
• {tenant_id}: Multi-tenant isolation identifier

Example:

Full RUFID:  rufid:a1b2c3d4e5f6:v1:default
Short RUFID: a1b2c3d4e5f6

Function Metadata

Each RUFID carries essential metadata:

{
  "rufid": "a1b2c3d4e5f6",
  "function_name": "authenticate_user",
  "signature": "(username: str, password: str) -> bool",
  "language": "python",
  "version": "v1",
  "created_at": "2024-01-01T00:00:00Z",
  "author": "user@example.com",
  "tenant_id": "default",
  "tags": ["auth", "security"],
  "dependencies": ["bcrypt", "jwt"],
  "metrics": {
    "usage_count": 15420,
    "avg_execution_time_ms": 12.3,
    "success_rate": 0.998
  }
}

RUFID Specification

Generation Algorithm

RUFIDs are generated using a deterministic hash algorithm:

def generate_rufid(function_name: str, source_code: str, signature: str, tenant_id: str) -> str:
    # 1. Normalize source code (remove comments, normalize whitespace)
    normalized_code = normalize(source_code)
    
    # 2. Create canonical representation
    canonical = f"{function_name}:{signature}:{normalized_code}"
    
    # 3. Generate SHA-256 hash
    hash_bytes = hashlib.sha256(canonical.encode()).digest()
    
    # 4. Encode to base62 (alphanumeric)
    rufid_hash = base62_encode(hash_bytes)[:12]
    
    # 5. Construct full RUFID
    return f"rufid:{rufid_hash}:v1:{tenant_id}"

Validation Rules

1. Length: Short RUFID must be exactly 12 characters
2. Characters: Only alphanumeric (a-z, A-Z, 0-9)
3. Uniqueness: Collision probability < 10^-15
4. Immutability: RUFIDs are immutable once created

Protocol Architecture

Multi-Protocol Support

The Relay Protocol supports multiple transport protocols through a unified translation layer:

┌─────────────────────────────────────────────────┐
│                   Client Request                 │
└─────────────┬───────────┬───────────┬──────────┘
              ▼           ▼           ▼
         ┌────────┐  ┌────────┐  ┌────────┐
         │  REST  │  │GraphQL │  │  gRPC  │
         └───┬────┘  └───┬────┘  └───┬────┘
             └───────────┼───────────┘
                         ▼
              ┌──────────────────────┐
              │  Protocol Federation  │
              │    Translation Layer  │
              └──────────────────────┘
                         │
                         ▼
              ┌──────────────────────┐
              │    RUFID Engine      │
              └──────────────────────┘
                         │
                         ▼
              ┌──────────────────────┐
              │   PostgreSQL + Cache  │
              └──────────────────────┘

Component Architecture

Core Components:
  RUFID Engine:
    - Generation: Deterministic hash generation
    - Validation: Format and integrity checks
    - Resolution: High-speed lookup with caching
    
  Protocol Federation:
    - REST Translator: HTTP/JSON translation
    - GraphQL Resolver: Query/mutation handling
    - gRPC Service: Protobuf serialization
    - WebSocket Manager: Real-time subscriptions
    
  Storage Layer:
    - PostgreSQL: Primary data store
    - Redis Cache: Hot path optimization
    - Index Manager: B-tree and hash indexes
    
  Execution Engine:
    - Sandbox: Isolated execution environment
    - Resource Limits: CPU, memory, time constraints
    - Telemetry: Execution metrics and tracing

API Specification

REST API

Create RUFID

POST /api/v1/functions/create
Content-Type: application/json

{
  "function_name": "calculate_discount",
  "source_code": "def calculate_discount(price, rate): ...",
  "signature": "(price: float, rate: float) -> float",
  "language": "python",
  "description": "Calculate discount amount",
  "tags": ["commerce", "pricing"]
}

Response:
{
  "rufid": "rufid:x7y8z9a0b1c2:v1:default",
  "rufid_short": "x7y8z9a0b1c2",
  "import_statement": "from relay.rufid import x7y8z9a0b1c2 as calculate_discount",
  "share_url": "https://rufid.run/x7y8z9a0b1c2",
  "api_endpoint": "/api/v1/functions/x7y8z9a0b1c2/execute"
}

Resolve RUFID

POST /api/v1/functions/resolve
Content-Type: application/json

{
  "rufid": "x7y8z9a0b1c2",
  "version": "v1"
}

Response:
{
  "function_id": "uuid-1234-5678",
  "rufid": "x7y8z9a0b1c2",
  "version": "v1",
  "accessible": true,
  "cached": true,
  "resolution_time_ms": 1.8
}

Execute Function

POST /api/v1/functions/{rufid}/execute
Content-Type: application/json

{
  "arguments": {
    "price": 100.00,
    "rate": 0.15
  }
}

Response:
{
  "result": 15.00,
  "execution_time_ms": 2.3,
  "status": "success"
}

GraphQL Schema

type Query {
  resolveRUFID(rufid: String!): RUFIDResolution
  listFunctions(
    search: String
    tags: [String]
    limit: Int = 20
    offset: Int = 0
  ): FunctionList
  getFunctionMetrics(rufid: String!): FunctionMetrics
}

type Mutation {
  createFunction(input: CreateFunctionInput!): Function
  executeFunction(rufid: String!, args: JSON!): ExecutionResult
  deleteFunction(rufid: String!): Boolean
}

type Subscription {
  functionExecutions(rufid: String): ExecutionEvent
  systemEvents: SystemEvent
}

type Function {
  rufid: String!
  shortRufid: String!
  name: String!
  signature: String!
  language: String!
  version: String!
  createdAt: DateTime!
  metrics: FunctionMetrics
}

gRPC Service

service RelayProtocolService {
  rpc CreateRUFID(CreateRUFIDRequest) returns (CreateRUFIDResponse);
  rpc ResolveRUFID(ResolveRUFIDRequest) returns (ResolveRUFIDResponse);
  rpc ExecuteFunction(ExecuteFunctionRequest) returns (ExecuteFunctionResponse);
  rpc StreamExecutions(StreamRequest) returns (stream ExecutionEvent);
}

message CreateRUFIDRequest {
  string function_name = 1;
  string source_code = 2;
  string signature = 3;
  string language = 4;
  repeated string tags = 5;
}

message CreateRUFIDResponse {
  string rufid = 1;
  string import_statement = 2;
  string share_url = 3;
}

Federation Protocol

Node Registration

Federation nodes register with the network to participate in RUFID discovery:

{
  "node_id": "node-east-1",
  "endpoint": "https://east1.relay.network",
  "capabilities": {
    "languages": ["python", "javascript", "go"],
    "max_concurrent": 1000,
    "protocols": ["rest", "grpc", "graphql"]
  },
  "auth": {
    "certificate": "-----BEGIN CERTIFICATE-----...",
    "public_key": "ssh-rsa AAAAB3..."
  }
}

Discovery Protocol

Nodes broadcast and discover RUFIDs across the federation:

Node A                    Registry                   Node B
  │                           │                         │
  ├──Register Node───────────►│                         │
  │                           ├──Broadcast──────────────►
  │                           │                         │
  │◄──Node List───────────────┤                         │
  │                           │                         │
  ├──Discover RUFID──────────►│                         │
  │                           ├──Query Nodes────────────►
  │                           │◄─────Results────────────┤
  │◄──Federated Results───────┤                         │

Synchronization

Nodes synchronize RUFID catalogs using incremental sync:

async def sync_catalog(since: datetime, node: FederatedNode):
    # Get changes since last sync
    changes = await get_catalog_changes(since)
    
    # Send to peer node
    response = await node.sync({
        "added": changes.added,
        "updated": changes.updated,
        "deleted": changes.deleted,
        "timestamp": datetime.utcnow()
    })
    
    # Apply peer changes locally
    await apply_peer_changes(response)

Security Model

Authentication

The protocol supports multiple authentication methods:

1. JWT Tokens: Bearer token authentication
2. API Keys: Static key authentication
3. mTLS: Certificate-based mutual TLS
4. OAuth 2.0: Third-party authorization

Authorization

Fine-grained permissions control access:

Permissions:
  rufid.create: Create new RUFIDs
  rufid.read: Resolve and read RUFIDs
  rufid.execute: Execute functions
  rufid.delete: Delete RUFIDs
  rufid.admin: Full administrative access
  
Roles:
  developer:
    - rufid.create
    - rufid.read
    - rufid.execute
  
  consumer:
    - rufid.read
    - rufid.execute
  
  admin:
    - rufid.*

Audit Logging

All operations are logged for compliance:

{
  "timestamp": "2024-01-01T12:00:00Z",
  "operation": "rufid.execute",
  "rufid": "x7y8z9a0b1c2",
  "user": "user@example.com",
  "tenant": "default",
  "ip": "192.168.1.100",
  "result": "success",
  "duration_ms": 2.3
}

Performance Requirements

SLA Targets

Metric	Target	99th Percentile
RUFID Generation	< 5ms	< 10ms
RUFID Resolution	< 2ms	< 3ms
Function Execution	< 50ms	< 100ms
Federation Sync	< 100ms	< 200ms
Cache Hit Rate	> 95%	-
Availability	99.99%	-

Optimization Strategies

1. In-Memory Caching: Hot RUFIDs cached with TTL
2. Connection Pooling: Reuse database connections
3. Index Optimization: B-tree on rufid_short, hash on tenant_id
4. Batch Operations: Bulk RUFID resolution
5. CDN Distribution: Static assets and share URLs

Implementation Guidelines

Client Libraries

Official SDKs provide native integration:

Python

from relay_protocol import RelayClient

client = RelayClient(api_key="...")
rufid = client.create_function(
    name="process_order",
    code=process_order_func,
    signature="(order: Order) -> bool"
)

# Direct import
from relay.rufid import x7y8z9a0b1c2 as process_order
result = process_order(my_order)

JavaScript/TypeScript

import { RelayClient } from '@relay/protocol';

const client = new RelayClient({ apiKey: '...' });
const rufid = await client.createFunction({
  name: 'processOrder',
  code: processOrderFunc,
  signature: '(order: Order) => boolean'
});

// Dynamic import
const { processOrder } = await import(`relay://x7y8z9a0b1c2`);
const result = await processOrder(myOrder);

Go

import "github.com/relay-protocol/go-sdk"

client := relay.NewClient("api-key")
rufid, _ := client.CreateFunction(relay.Function{
    Name: "ProcessOrder",
    Code: processOrderFunc,
    Signature: "func(Order) bool",
})

// Execute
result, _ := client.Execute(rufid, order)

Error Handling

Standardized error codes across all protocols:

Code	Name	Description
1001	INVALID_RUFID	RUFID format validation failed
1002	RUFID_NOT_FOUND	RUFID does not exist
1003	PERMISSION_DENIED	Insufficient permissions
1004	EXECUTION_TIMEOUT	Function execution exceeded timeout
1005	RATE_LIMITED	Request rate limit exceeded
2001	FEDERATION_UNREACHABLE	Cannot reach federation node
2002	SYNC_CONFLICT	Catalog sync conflict

Monitoring

Required metrics for production deployments:

Metrics:
  System:
    - relay_protocol_requests_total
    - relay_protocol_request_duration_seconds
    - relay_protocol_errors_total
    
  RUFID:
    - relay_rufid_creations_total
    - relay_rufid_resolutions_total
    - relay_rufid_cache_hits_ratio
    
  Execution:
    - relay_function_executions_total
    - relay_function_execution_duration_seconds
    - relay_function_errors_total
    
  Federation:
    - relay_federation_nodes_active
    - relay_federation_sync_duration_seconds
    - relay_federation_discovery_requests_total

Appendix

Reference Implementation

The reference implementation is available at:

• Repository: https://github.com/relay-protocol/reference
• Documentation: https://docs.relay-protocol.org
• Playground: https://try.relay-protocol.org

Version History

Version	Date	Changes
2.0.0	2024-01	Protocol federation, multi-protocol support
1.5.0	2023-10	Performance optimizations, 92% faster resolution
1.0.0	2023-06	Initial specification release

Contributing

Protocol improvements are managed through:

1. RFC Process: Submit proposals as GitHub issues
2. Reference Implementation: Prove concepts with code
3. Community Review: 30-day comment period
4. Adoption: Gradual rollout with compatibility period

---

This specification is released under the MIT License and is maintained by the Relay Protocol Consortium.