Reference Manual - SANCA999

Network Topology

SANCA999 avoids centralized message brokers to reduce single points of failure. The registry operates purely as a discovery layer; nodes handle data transmission directly via peer-to-peer handshakes over TCP port 9999.

Node Lifecycle

Bootstrap: Node requests the current routing table from registry.sanca.internal.
Gossip: Node broadcasts its presence to 3 randomly selected peers from the routing table via UDP.
Active: Node is eligible to receive tasks. Heartbeats are sent every 30 seconds.
Eviction: If a node misses 3 consecutive heartbeats, it is marked as dead. Rejoining requires a full TLS handshake.

Warning: Do not attempt to run the registry on burstable CPU instances (e.g., AWS T-series). The cryptographic overhead of node handshakes will exhaust CPU credits during a cold restart of the cluster.

Writing Custom Modules

The agent is extensible through PHP classes implementing the base contract. Modules are loaded dynamically at boot time based on the agent.conf file.

Modules must adhere to strict memory limits. The daemon will kill any child process exceeding 128MB of RAM to preserve node stability.

<?php
namespace Sanca\Modules;

use Sanca\Core\AgentContext;
use Sanca\Core\ModuleInterface;

class NetworkScanner implements ModuleInterface 
{
    private array $targets;

    public function __construct(array $config) 
    {
        if (!isset($config['cidr'])) {
            throw new \InvalidArgumentException("Missing 'cidr' configuration.");
        }
        $this->targets = $config['cidr'];
    }

    public function execute(AgentContext $ctx): void 
    {
        $ctx->log("Initiating scan on " . implode(', ', $this->targets));
        
        // Modules must yield control back to the event loop
        // Avoid blocking I/O calls without timeouts.
        $stream = stream_socket_client("tcp://{$this->targets[0]}:80", $errno, $errstr, 2);
        
        if (!$stream) {
            $ctx->reportFailure("Connection timeout");
            return;
        }

        $ctx->reportSuccess("Port 80 reachable");
        fclose($stream);
    }
}

Environment Configuration

Node behavior is dictated strictly by the environment variables present at process start. Hot-reloading is not supported; restart the daemon to apply changes.

Variable	Default	Description
`SANCA_NODE_ID`	Generated	Unique identifier for the node. Must be alphanumeric.
`SANCA_REGISTRY_URI`	`tcp://127.0.0.1:9998`	Address of the central routing registry.
`SANCA_LOG_LEVEL`	`WARN`	Verbosity of the daemon output. Acceptable values: DEBUG, INFO, WARN, FATAL.
`SANCA_MAX_PAYLOAD`	`4096`	Maximum task payload size in kilobytes. Packets exceeding this are dropped silently.

Operational Runbook

Strict procedures for handling known failure states.

Split-Brain Resolution

In the event of a network partition lasting longer than 5 minutes, isolated node clusters will elect temporary registries. When the partition heals, nodes will panic due to conflicting registry signatures.

Action required: You must issue a SIGUSR1 to the primary registry to force a cluster-wide key rotation and routing table flush.

kill -SIGUSR1 $(cat /var/run/sanca-registry.pid)

Storage Exhaustion

Agents buffer metrics locally if the registry is unreachable. This buffer is capped at 50MB. Once full, the agent drops the oldest metrics (ring buffer). Do not manually clear the SQLite buffer file while the daemon is running, as this will corrupt the WAL.