@godprotocol/oracle

@godprotocol/oracle

A distributed coordination server for decentralized repositories.

The Oracle module in the God Protocol framework ensures seamless synchronization of data, repositories, and content across network nodes, delivering consistency, resilience, and real-time scalability for thousands of distributed systems.

Features

• Repository Synchronization: Automatically syncs repositories across mirrors and servers.
• Mirror-Aware Architecture: Maintains lightweight cache and propagation queues for mirrored nodes.
• Horizontal Scalability: Supports thousands of servers via Oracle Clients and async propagation queues.
• Authentication Layer: Token-based client identification and authorization.
• Self-Propagating Network: Oracles automatically sync peers and push updates to connected servers.

Installation

Install the Oracle module using npm:

npm install @godprotocol/oracle

Quick Start

Set up an Oracle server with the following example:

import sync from "@godprotocol/oracle/index.js";
import { repo_config } from "./repos.js";

const server_details = {
  hostname: process.env.HOSTNAME || "localhost",
  port: process.env.PORT || 8080,
};

sync(server_details, repo_config).then((handler) => {
  const http = require("http");
  http.createServer(handler).listen(server_details.port, () => {
    console.log(
      `Oracle server running at http://${server_details.hostname}:${server_details.port}`
    );
  });
});

API Reference

Class: Oracle

Method	Description
constructor(mirror)	Initializes an Oracle instance with a mirror repository for coordination.
oracle.sync(server, mirror)	Starts synchronization and returns a Node.js-compatible HTTP handler.
oracle.authenticate({ client })	Registers and authenticates a client node.
oracle.add_repo({ filter, repo }, { client })	Adds a new repository with an optional filter (e.g., regex for content paths).
oracle.write({ path, content }, client)	Writes content to one or more matching repositories and propagates updates across mirrors.
oracle.write_bulk(contents, client)	Writes multiple files efficiently in a single operation.
oracle.read(path)	Reads content from distributed repositories, returning both data and its source repo.
oracle.propagate(payload, callback?)	Propagates data or sync signals across all registered servers.

HTTP Endpoints

These endpoints are exposed by the Oracle server’s route handler:

Endpoint	Method	Description
/	GET	Returns a simple HTML response confirming the Oracle server is active.
/oracle/authenticate	POST	Registers or authenticates a client. Returns an authorization token.
/oracle/read	POST	Reads data from one or more repositories. Requires Authorization header.
/oracle/write	POST	Writes data to repositories and synchronizes it across mirrors. Requires Authorization header.
/oracle/write_bulk	POST	Writes multiple data entries in bulk. Requires Authorization header.
/oracle/add_repo	POST	Adds a new repository with a given filter and metadata. Requires Authorization header.
/oracle/on_sync	POST	Called when a remote sync event occurs. Used internally for mirror updates.
/oracle/sync_repos	POST	Synchronizes repository metadata across nodes.
/oracle/sync_content_location	POST	Synchronizes specific content location data across mirrors.

Notes:

• All POST endpoints expect JSON body.
• Requests to /oracle/* (except /authenticate) require an Authorization header.
• The server responds with JSON and appropriate HTTP status codes (200, 401, 404, 500).

Network Design

The Oracle is built for non-blocking distributed propagation. When a write or repository sync occurs:

• The Oracle immediately acknowledges the client.
• Updates are asynchronously propagated across mirrors and peer Oracles using a queued propagation system.
• Mirrors cache only content location metadata (not full data) to prevent stale reads.

This design ensures fast request-response cycles and consistent eventual synchronization across the network.

Example: Oracle Client

Clients communicate with Oracle servers via a simple JSON-based POST interface:

import { repo_any } from "./repos.js";
import { Oracle as OracleClient } from "godprotocol";

const server = { hostname: "server-oracle.app", port: 80 };
const client_details = { hostname: "client-oracle.app", port: 80 };

const oracle = new OracleClient({ server, port: 1909 });
await oracle.sync(client_details, repo_any);

await oracle.add_repo({
  filter: "*",
  repo: repo_any,
});

await oracle.write(
  "data/record.json",
  JSON.stringify({ id: 1, name: "John Doe" })
);

const data = await oracle.read("data/record.json");
console.log(data); // '{"id":1,"name":"John Doe"}'

Related Packages

Package	Description
@godprotocol/repositories	Repository management and file abstractions
godprotocol	Core framework for decentralized computation
generalised-datastore	Data storage and remote access integration layer

License

MIT © Savvy