gRPC API Reference

Primatomic exposes its distributed coordination primitives through multiple specialized gRPC services. Each service provides focused functionality for key-value storage, locks, memory regions, and cluster management with strong consistency guarantees.

Service Overview

KeyValueService - Atomic Key-Value Operations

service KeyValueService {
  rpc CreateNamespace(CreateNamespaceRequest) returns (CreateNamespaceResponse);
  rpc GetKey(GetKeyRequest) returns (GetKeyResponse);
  rpc PutKey(PutKeyRequest) returns (PutKeyResponse);
  rpc DeleteKey(DeleteKeyRequest) returns (DeleteKeyResponse);
  rpc ListKeys(ListKeysRequest) returns (ListKeysResponse);
  rpc CompareAndSwap(CompareAndSwapRequest) returns (CompareAndSwapResponse);
}

LockService - Distributed Synchronization

service LockService {
  // Exclusive Locks
  rpc CreateLock(CreateLockRequest) returns (CreateLockResponse);
  rpc DescribeLock(DescribeLockRequest) returns (DescribeLockResponse);
  rpc AcquireLock(AcquireLockRequest) returns (AcquireLockResponse);
  rpc ReleaseLock(ReleaseLockRequest) returns (ReleaseLockResponse);
  rpc ForceReleaseLock(ForceReleaseLockRequest) returns (ForceReleaseLockResponse);

  // Read-Write Locks
  rpc CreateRWLock(CreateRWLockRequest) returns (CreateRWLockResponse);
  rpc DescribeRWLock(DescribeRWLockRequest) returns (DescribeRWLockResponse);
  rpc AcquireRWLock(AcquireRWLockRequest) returns (AcquireRWLockResponse);
  rpc ReleaseRWLock(ReleaseRWLockRequest) returns (ReleaseRWLockResponse);
}

MemoryService - High-Performance Memory Regions

service MemoryService {
  rpc AllocateMemory(AllocateMemoryRequest) returns (AllocateMemoryResponse);
  rpc DescribeMemory(DescribeMemoryRequest) returns (DescribeMemoryResponse);
  rpc ResizeMemory(ResizeMemoryRequest) returns (ResizeMemoryResponse);
  rpc FreeMemory(FreeMemoryRequest) returns (FreeMemoryResponse);
  rpc WriteMemory(WriteMemoryRequest) returns (WriteMemoryResponse);
  rpc ReadMemory(ReadMemoryRequest) returns (ReadMemoryResponse);
  rpc ListMemoryRegions(ListMemoryRegionsRequest) returns (ListMemoryRegionsResponse);
}

Protocol Characteristics

Request Routing

• Leader Forwarding: All write operations are automatically forwarded to the cluster leader
• Linearizable Consistency: Operations observe a consistent global ordering through Raft consensus
• Automatic Failover: Clients automatically discover and connect to new leaders during failover

Authentication & Authorization

• Credential Authentication: All operations require valid credential ID authentication via authorization metadata header
• Namespace Isolation: Credential IDs can only access resources within authorized namespaces
• API Versioning: Clients must specify api-version header for compatibility

Error Handling

• Standard gRPC Codes: Operations return standard gRPC status codes (OK, NOT_FOUND, ALREADY_EXISTS, etc.)
• Detailed Messages: Error responses include descriptive messages for debugging
• Retry Semantics: Idempotent operations can be safely retried with the same request ID

Authentication

JWT Token Format

{
  "sub": "user-id",
  "iat": 1640995200,
  "exp": 1641081600,
  "namespaces": ["myapp", "shared"],
  "access": ["read", "write", "admin"]
}

Header Requirements

authorization: Bearer <jwt-token>
api-version: v1
request-id: <unique-uuid>

Python SDK Usage

Basic Client Setup

import primatomic

# Connect with automatic leader discovery
client = primatomic.Client("localhost:50051", token="jwt-token-here")

# Alternative: explicit leader endpoint
leader_client = primatomic.Client.from_leader("localhost:50051", token="jwt-token-here")

Key-Value Operations

# Basic CRUD operations
await client.put_key("config", b'{"debug": true}', namespace="myapp")
value = await client.get_key("config", namespace="myapp")
await client.delete_key("config", namespace="myapp")

# Atomic compare-and-swap
success = await client.compare_and_swap(
    key="counter",
    expected_value=b"5",
    new_value=b"6",
    namespace="myapp"
)

Distributed Locking

# Exclusive locks with automatic cleanup
async with client.lock("resource", namespace="myapp", ttl=30):
    # Critical section - only one client can execute this
    await perform_exclusive_operation()

# Read/write locks for concurrent readers
async with client.read_lock("data", namespace="myapp", ttl=60):
    # Multiple readers can access simultaneously
    data = await read_shared_data()

async with client.write_lock("data", namespace="myapp", ttl=60):
    # Exclusive write access
    await update_shared_data()

Memory Regions

# Allocate high-performance shared memory
region_id = await client.allocate_memory(1024*1024, namespace="myapp")

# Write data efficiently
await client.write_memory(region_id, offset=0, data=b"shared data")

# Read data with zero-copy optimization
data = await client.read_memory(region_id, offset=0, length=100)

# Clean up resources
await client.free_memory(region_id, namespace="myapp")

Watch Operations

# Watch for key changes in real-time
async for event in client.watch_keys(prefix="config/", namespace="myapp"):
    print(f"Key {event.key} changed: {event.value}")

# Watch lock acquisitions and releases
async for event in client.watch_locks(namespace="myapp"):
    print(f"Lock {event.key} {event.action} by {event.owner}")

Error Handling

Common Status Codes

• UNAUTHENTICATED: Invalid or expired credential ID
• PERMISSION_DENIED: Insufficient access for namespace or operation
• NOT_FOUND: Requested key, lock, or memory region does not exist
• ALREADY_EXISTS: Resource already exists (e.g., duplicate namespace creation)
• DEADLINE_EXCEEDED: Operation timeout (configurable per request)
• UNAVAILABLE: Cluster leader unavailable or undergoing election

Retry Strategy

import backoff
import grpc

@backoff.on_exception(
    backoff.expo,
    grpc.RpcError,
    max_tries=3,
    giveup=lambda e: e.code() in [grpc.StatusCode.PERMISSION_DENIED]
)
async def reliable_operation():
    return await client.get_key("important-data", namespace="myapp")

This gRPC API provides the foundation for building distributed applications requiring coordination, with comprehensive language support and production-ready operational features.