HPKV RIOC API

Business+ Feature

This feature is available exclusively to Business and Enterprise plan subscribers. Please visit our pricing page for more information.

RIOC (Remote IO Control)

RIOC is a high-performance RPC protocol designed specifically for HPKV, offering the fastest possible way to interact with your data. Available in Business and Enterprise plans, RIOC provides direct, low-latency access to HPKV with robust security through TLS 1.3.

Security

RIOC uses TLS 1.3 for authentication and encryption. Your certificates will be automatically generated and available in your Dashboard. Enterprise users can optionally disable TLS for private setups where security is managed through other means.

Key Benefits

  • Ultra-low latency communication (in the ~15µs range over network)
  • Efficient binary protocol
  • Native SDK support for Node.js, Python, and .NET
  • Secure by default with TLS 1.3
  • Support for batch operations
  • Connection pooling and automatic reconnection
  • Atomic operations for counters and rate limiters

Note

Enterprise customers have access to a local vectored call interface that bypasses network communication entirely, reducing operation latency to the ~300ns range. This is ideal for applications requiring extreme low latency and running on the same machine as HPKV.

Open Source Client

The RIOC client SDKs are available as open source software on GitHub. You can find the source code, contribute, or create custom implementations.

RIOC GitHub Repository

The repository includes client SDKs for Node.js, Python, and .NET, core API documentation, implementation examples, and client protocol specifications. All client code is licensed under the Apache License 2.0.

Connecting with RIOC

RIOC is available through our official SDKs. Here's how to establish a connection:

const { RiocClient } = require('@hpkv/rioc');

// Create client configuration
const config = {
  host: 'your-hpkv-host',
  port: 7000,  // Default RIOC port
  timeoutMs: 5000,  // Optional timeout in milliseconds
  tls: {
    caPath: 'path/to/ca.crt',          // CA certificate
    certificatePath: 'path/to/client.crt', // Client certificate
    keyPath: 'path/to/client.key',        // Client private key
    verifyHostname: 'your-hpkv-host',     // Server hostname to verify
    verifyPeer: true                      // Enable certificate verification
  }
};

// Create client
const client = new RiocClient(config);

Basic Operations

RIOC provides high-performance operations for working with HPKV:

// Get current timestamp (required for write operations)
const timestamp = RiocClient.getTimestamp();

// Store a value (requires timestamp)
const key = Buffer.from('user:123');
const value = Buffer.from('John Doe');
client.insert(key, value, timestamp);

// Retrieve a value (no timestamp needed)
const retrievedValue = client.get(key);
console.log('Retrieved:', retrievedValue.toString());

// Range query - get all users from 100 to 200
const startKey = Buffer.from('user:100');
const endKey = Buffer.from('user:200');
const results = client.rangeQuery(startKey, endKey, 50); // limit to 50 records

for (const { key, value } of results) {
  console.log(`${key.toString()}: ${value.toString()}`);
}

// Delete a value (requires timestamp)
const deleteTimestamp = RiocClient.getTimestamp();
client.delete(key, deleteTimestamp);

// Atomic increment/decrement
const counterKey = Buffer.from('counter:123');
const newValue = client.atomicIncDec(counterKey, 1, RiocClient.getTimestamp()); // Increment by 1
console.log('New counter value:', newValue);

// Batch operations
const batch = client.createBatch();
const batchTimestamp = RiocClient.getTimestamp();

batch.addGet(Buffer.from('key1'));
batch.addInsert(Buffer.from('key2'), Buffer.from('value2'), batchTimestamp);
batch.addDelete(Buffer.from('key3'), batchTimestamp);
batch.addRangeQuery(Buffer.from('user:100'), Buffer.from('user:200'), 10);

const tracker = batch.executeAsync();
tracker.wait(1000);  // Wait up to 1 second for completion

// Get results from the batch
const batchGetResult = tracker.getResponse(0);
const batchRangeResult = tracker.getRangeQueryResponse(3);

// Clean up resources
tracker.dispose();
batch.dispose();

Note

Please refer to SDK Guides for more information on the RIOC API usage.

Enterprise Setup

Enterprise users can run HPKV locally and optionally disable TLS for improved performance in secure environments:

// Initialize without TLS for Enterprise setup
const client = new HPKVClient({
  host: 'localhost',
  port: 7000,
  tls: false  // Disable TLS
});

await client.connect();

Best Practices

  • Preferably use timestamps from RiocClient.getTimestamp() for write operations
  • Use connection pooling for concurrent operations
  • Keep TLS enabled unless you have a specific reason not to
  • Use batch operations for multiple related operations
  • Monitor connection health and implement reconnection logic
  • Store certificates securely and rotate them periodically