Files
zeekayandHanzo Dev 0c08bd1d94 Go 1.27.1, and the code it can say more simply
Modules declare go 1.27.1 and the build images follow. go fix applied the
modernizers; omitzero is not applied, since it changes what the JSON says.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-17 01:01:10 -07:00

437 lines
14 KiB
Go

// Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// Package object/zap.go — Native ZAP binary protocol node.
//
// Cloud-api is a first-class ZAP node. NO gateways, NO proxies, NO sidecars,
// NO HTTP translation layers. Everything is ZAP-to-ZAP:
//
// client → cloud-api:9999 (ZAP binary)
// cloud-api → kv:9999 (ZAP binary)
// cloud-api → sql:9999 (ZAP binary)
//
// Service handlers are registered via RegisterCloudHandler() from the
// controllers package (avoids circular imports).
package object
import (
"context"
"encoding/json"
"fmt"
"log/slog"
"os"
"sync"
"time"
"github.com/hanzoai/ai/log"
"github.com/luxfi/zap"
)
// ── Message types ───────────────────────────────────────────────────────
//
// Cloud service types (100-199):
//
// 100 = Cloud service request (method dispatch)
//
// Backend types (300-399, matches sidecar protocol):
//
// 300 = SQL query/exec
// 301 = KV get/set/cmd
const (
// Cloud service — native binary RPC, NO HTTP.
MsgTypeCloud uint16 = 100
// Gateway → cloud-api (HTTP-over-ZAP from gateway proxy).
// Request: method(0:Text) + path(8:Text) + headers(16:Bytes) + body(24:Bytes) + query(32:Text)
// Response: status(0:Uint32) + body(4:Bytes) + headers(12:Bytes)
MsgTypeHTTPRequest uint16 = 200
// Backend sidecar protocol (KV/SQL embedded servers).
MsgTypeSQL uint16 = 300
MsgTypeKV uint16 = 301
MsgTypeDocdb uint16 = 303
// ── Cloud service message layout ────────────────────────────────
// Request: method(0:Text) + auth(8:Text) + body(16:Bytes)
// Response: status(0:Uint32) + body(4:Bytes) + error(12:Text)
CloudReqMethod = 0
CloudReqAuth = 8
CloudReqBody = 16
CloudRespStatus = 0
CloudRespBody = 4
CloudRespError = 12
// ── Gateway response layout ─────────────────────────────────────
// Response: status(0:Uint32) + body(4:Bytes) + headers(12:Bytes)
//
// The same three slots as the cloud response, and the third is NOT the same
// field: a gateway answer carries headers where a cloud answer carries an
// error. Named here rather than borrowed, so the slot that means two things
// says which one it means at each use.
GatewayRespStatus = 0
GatewayRespBody = 4
GatewayRespHeaders = 12
// ── Sidecar message layout (matches ORM driver) ─────────────────
sidecarReqPath = 4
sidecarReqBody = 12
sidecarRespStatus = 0
sidecarRespBody = 4
)
// ── Package state ───────────────────────────────────────────────────────
var (
zapNode *zap.Node
kvPeerID string
sqlPeerID string
docdbPeerID string
zapMu sync.RWMutex
zapReady bool
)
// ── Initialization ──────────────────────────────────────────────────────
// InitZap starts the ZAP node and connects to KV and SQL peers.
func InitZap() {
if os.Getenv("ZAP_ENABLED") != "true" {
log.Info("ZAP: disabled (set ZAP_ENABLED=true)")
return
}
port := 9999
if p := os.Getenv("ZAP_PORT"); p != "" {
fmt.Sscanf(p, "%d", &port)
}
nodeID := os.Getenv("ZAP_NODE_ID")
if nodeID == "" {
nodeID = "cloud-api"
}
node := zap.NewNode(zap.NodeConfig{
NodeID: nodeID,
Port: port,
NoDiscovery: true,
Logger: slog.Default(),
})
if err := node.Start(); err != nil {
log.Error("ZAP: failed to start node: %v", err)
return
}
log.Info("ZAP: node started on :%d (id=%s)", port, nodeID)
zapMu.Lock()
zapNode = node
zapReady = true
zapMu.Unlock()
// Connect to backend peers asynchronously.
kvAddr := os.Getenv("ZAP_KV_ADDR")
if kvAddr == "" {
kvAddr = "hanzo-kv:9999"
}
go connectPeer(node, kvAddr, "kv", &kvPeerID)
sqlAddr := os.Getenv("ZAP_SQL_ADDR")
if sqlAddr == "" {
sqlAddr = "sql.hanzo.svc:9999"
}
go connectPeer(node, sqlAddr, "sql", &sqlPeerID)
// Datastore (datastore) is reached directly (object/datastore.go), NOT via a
// ZAP peer — the datastore image serves datastore on :8123/:9000, not a ZAP
// bridge, and the unified cloud binary never starts this node. See InitDatastore.
// DocDB (FerretDB) — optional, document database via SQL wire protocol.
if docdbAddr := os.Getenv("ZAP_DOCDB_ADDR"); docdbAddr != "" {
go connectPeer(node, docdbAddr, "docdb", &docdbPeerID)
}
}
// GetZapNode returns the ZAP node for handler registration.
// Used by controllers package to register service handlers.
func GetZapNode() *zap.Node {
zapMu.RLock()
defer zapMu.RUnlock()
return zapNode
}
// ZapEnabled returns true if the ZAP node is running.
func ZapEnabled() bool {
zapMu.RLock()
defer zapMu.RUnlock()
return zapReady && zapNode != nil
}
// StopZap gracefully shuts down the ZAP node.
func StopZap() {
zapMu.Lock()
defer zapMu.Unlock()
if zapNode != nil {
zapNode.Stop()
zapNode = nil
zapReady = false
log.Info("ZAP: node stopped")
}
}
// connectPeer retries connecting to a ZAP peer with backoff.
func connectPeer(node *zap.Node, addr, name string, peerIDOut *string) {
peersBefore := make(map[string]bool)
for _, p := range node.Peers() {
peersBefore[p] = true
}
for attempt := 1; attempt <= 30; attempt++ {
if err := node.ConnectDirect(addr); err != nil {
log.Warn("ZAP: connect %s (%s) attempt %d: %v", name, addr, attempt, err)
time.Sleep(2 * time.Second)
continue
}
for _, p := range node.Peers() {
if !peersBefore[p] {
zapMu.Lock()
*peerIDOut = p
zapMu.Unlock()
log.Info("ZAP: connected to %s at %s (peer=%s)", name, addr, p)
return
}
}
peers := node.Peers()
if len(peers) > 0 {
zapMu.Lock()
*peerIDOut = peers[len(peers)-1]
zapMu.Unlock()
log.Info("ZAP: connected to %s at %s (peer=%s)", name, addr, *peerIDOut)
return
}
}
log.Error("ZAP: failed to connect to %s at %s after 30 attempts", name, addr)
}
// ── KV client (native ZAP-to-ZAP) ──────────────────────────────────────
// ZapKVGet fetches a key from KV via native ZAP binary.
func ZapKVGet(ctx context.Context, key string) (string, error) {
zapMu.RLock()
node, peer := zapNode, kvPeerID
zapMu.RUnlock()
if node == nil || peer == "" {
return "", fmt.Errorf("zap: kv not connected")
}
body, _ := json.Marshal(map[string]string{"key": key})
status, resp, err := zapCallBackend(ctx, node, peer, MsgTypeKV, "/get", body)
if err != nil {
return "", err
}
if status != 200 || len(resp) == 0 {
return "", fmt.Errorf("zap: kv get %q: status %d", key, status)
}
var val string
if err := json.Unmarshal(resp, &val); err != nil {
return string(resp), nil
}
return val, nil
}
// ZapKVSet stores a key/value pair via native ZAP binary.
func ZapKVSet(ctx context.Context, key, value string) error {
zapMu.RLock()
node, peer := zapNode, kvPeerID
zapMu.RUnlock()
if node == nil || peer == "" {
return fmt.Errorf("zap: kv not connected")
}
body, _ := json.Marshal(map[string]string{"key": key, "value": value})
status, _, err := zapCallBackend(ctx, node, peer, MsgTypeKV, "/set", body)
if err != nil {
return err
}
if status != 200 {
return fmt.Errorf("zap: kv set %q: status %d", key, status)
}
return nil
}
// ZapKVSetEx stores a key/value with TTL via native ZAP binary.
func ZapKVSetEx(ctx context.Context, key, value string, ttlSeconds int) error {
zapMu.RLock()
node, peer := zapNode, kvPeerID
zapMu.RUnlock()
if node == nil || peer == "" {
return fmt.Errorf("zap: kv not connected")
}
body, _ := json.Marshal(map[string]any{
"cmd": "SETEX",
"args": []any{key, ttlSeconds, value},
})
status, _, err := zapCallBackend(ctx, node, peer, MsgTypeKV, "/cmd", body)
if err != nil {
return err
}
if status != 200 {
return fmt.Errorf("zap: kv setex %q: status %d", key, status)
}
return nil
}
// ZapKVDel deletes a key via native ZAP binary.
func ZapKVDel(ctx context.Context, key string) error {
zapMu.RLock()
node, peer := zapNode, kvPeerID
zapMu.RUnlock()
if node == nil || peer == "" {
return fmt.Errorf("zap: kv not connected")
}
body, _ := json.Marshal(map[string]any{
"cmd": "DEL",
"args": []string{key},
})
_, _, err := zapCallBackend(ctx, node, peer, MsgTypeKV, "/cmd", body)
return err
}
// ── SQL client (native ZAP-to-ZAP) ─────────────────────────────────────
// ZapSQLQuery executes a read query via native ZAP binary.
func ZapSQLQuery(ctx context.Context, sql string, args ...any) ([]map[string]any, error) {
zapMu.RLock()
node, peer := zapNode, sqlPeerID
zapMu.RUnlock()
if node == nil || peer == "" {
return nil, fmt.Errorf("zap: sql not connected")
}
body, _ := json.Marshal(map[string]any{"sql": sql, "args": args})
status, resp, err := zapCallBackend(ctx, node, peer, MsgTypeSQL, "/query", body)
if err != nil {
return nil, err
}
if status != 200 {
return nil, fmt.Errorf("zap: sql query: status %d", status)
}
var rows []map[string]any
if err := json.Unmarshal(resp, &rows); err != nil {
return nil, fmt.Errorf("zap: sql unmarshal: %w", err)
}
return rows, nil
}
// ZapSQLExec executes a write query via native ZAP binary.
func ZapSQLExec(ctx context.Context, sql string, args ...any) error {
zapMu.RLock()
node, peer := zapNode, sqlPeerID
zapMu.RUnlock()
if node == nil || peer == "" {
return fmt.Errorf("zap: sql not connected")
}
body, _ := json.Marshal(map[string]any{"sql": sql, "args": args})
status, _, err := zapCallBackend(ctx, node, peer, MsgTypeSQL, "/exec", body)
if err != nil {
return err
}
if status != 200 {
return fmt.Errorf("zap: sql exec: status %d", status)
}
return nil
}
// ── DocDB client (native ZAP-to-ZAP → FerretDB) ─────────────────────────
// ZapDocdbQuery executes a read query on DocDB via native ZAP binary.
func ZapDocdbQuery(ctx context.Context, sql string, args ...any) ([]map[string]any, error) {
zapMu.RLock()
node, peer := zapNode, docdbPeerID
zapMu.RUnlock()
if node == nil || peer == "" {
return nil, fmt.Errorf("zap: docdb not connected")
}
body, _ := json.Marshal(map[string]any{"sql": sql, "args": args})
status, resp, err := zapCallBackend(ctx, node, peer, MsgTypeDocdb, "/query", body)
if err != nil {
return nil, err
}
if status != 200 {
return nil, fmt.Errorf("zap: docdb query: status %d", status)
}
var rows []map[string]any
if err := json.Unmarshal(resp, &rows); err != nil {
return nil, fmt.Errorf("zap: docdb unmarshal: %w", err)
}
return rows, nil
}
// ZapDocdbExec executes a write query on DocDB via native ZAP binary.
func ZapDocdbExec(ctx context.Context, sql string, args ...any) error {
zapMu.RLock()
node, peer := zapNode, docdbPeerID
zapMu.RUnlock()
if node == nil || peer == "" {
return fmt.Errorf("zap: docdb not connected")
}
body, _ := json.Marshal(map[string]any{"sql": sql, "args": args})
status, _, err := zapCallBackend(ctx, node, peer, MsgTypeDocdb, "/exec", body)
if err != nil {
return err
}
if status != 200 {
return fmt.Errorf("zap: docdb exec: status %d", status)
}
return nil
}
// DocdbEnabled returns true if the docdb peer is connected.
func DocdbEnabled() bool {
zapMu.RLock()
defer zapMu.RUnlock()
return zapReady && docdbPeerID != ""
}
// ── Gateway response builder ─────────────────────────────────────────────
// BuildGatewayResponse creates a response in the gateway's expected format.
// Layout: status(0:Uint32) + body(4:Bytes) + headers(12:Bytes)
func BuildGatewayResponse(status uint32, body []byte, headers []byte) (*zap.Message, error) {
b := zap.NewBuilder(len(body) + len(headers) + 64)
obj := b.StartObject(20)
obj.SetUint32(GatewayRespStatus, status)
if len(body) > 0 {
obj.SetBytes(GatewayRespBody, body)
}
if len(headers) > 0 {
obj.SetBytes(GatewayRespHeaders, headers)
}
obj.FinishAsRoot()
data := b.FinishWithFlags(MsgTypeHTTPRequest << 8)
return zap.Parse(data)
}
// ── Backend message I/O ─────────────────────────────────────────────────
// zapCallBackend builds a sidecar-format message and sends it via ZAP.
func zapCallBackend(ctx context.Context, node *zap.Node, peerID string, msgType uint16, path string, body []byte) (uint32, []byte, error) {
b := zap.NewBuilder(len(body) + 128)
obj := b.StartObject(20)
obj.SetText(sidecarReqPath, path)
obj.SetBytes(sidecarReqBody, body)
obj.FinishAsRoot()
data := b.FinishWithFlags(msgType << 8)
msg, err := zap.Parse(data)
if err != nil {
return 0, nil, fmt.Errorf("zap: build: %w", err)
}
resp, err := node.Call(ctx, peerID, msg)
if err != nil {
return 0, nil, fmt.Errorf("zap: call: %w", err)
}
root := resp.Root()
return root.Uint32(sidecarRespStatus), root.Bytes(sidecarRespBody), nil
}
// ── Cloud service response builder ──────────────────────────────────────
// BuildCloudResponse creates a native ZAP cloud service response.
// Used by controllers to build responses for incoming cloud requests.
func BuildCloudResponse(status uint32, body []byte, errMsg string) (*zap.Message, error) {
b := zap.NewBuilder(len(body) + len(errMsg) + 64)
obj := b.StartObject(20)
obj.SetUint32(CloudRespStatus, status)
if len(body) > 0 {
obj.SetBytes(CloudRespBody, body)
}
if errMsg != "" {
obj.SetText(CloudRespError, errMsg)
}
obj.FinishAsRoot()
data := b.FinishWithFlags(MsgTypeCloud << 8)
return zap.Parse(data)
}