Key Features

• Device Profiles: Native support for hardware-specific dialects (e.g., CMCC RAX3000M, X86 Generic).
• Selective Imports: Import only what you need, avoiding overhead.
• Dual Transport: Supports both HTTP JSON-RPC (remote) and Unix Socket (local).
• Type-Safe API: Fully typed requests and responses.
• Context Aware: Support for context.Context cancellation and timeouts.

Installation

go get github.com/honeybbq/goubus/v2

Quick Start

1. Initialize Transport

import (
    "context"
    "github.com/honeybbq/goubus/v2"
)

ctx := context.Background()

// Remote via RPC (Requires rpcd and proper ACLs)
caller, _ := goubus.NewRpcClient(ctx, "192.168.1.1", "root", "password")

// Local via Unix Socket (Running on the device)
caller, _ := goubus.NewSocketClient(ctx, "/var/run/ubus/ubus.sock")

2. Use Device Specific Managers

Import the profile matching your hardware:

import (
    "github.com/honeybbq/goubus/v2/profiles/cmcc_rax3000m/system"
    "github.com/honeybbq/goubus/v2/profiles/cmcc_rax3000m/network"
)

// Initialize Managers
sysSvc := system.New(caller)
netSvc := network.New(caller)

// Fetch System Board Info
board, _ := sysSvc.Board(ctx)
fmt.Printf("Model: %s, Kernel: %s\n", board.Model, board.Kernel)

// Dump all network interfaces
ifaces, _ := netSvc.Dump(ctx)

3. Debugging & Logging

goubus natively supports log/slog. You can inject your own logger to see raw ubus interactions (requests and responses):

import "log/slog"

// Create a debug logger
logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelDebug}))

// Inject it into the transport
caller.SetLogger(logger)

Implemented Objects

Project Architecture

goubus is designed with a multi-layer architecture for code reuse:

• Core Layer (goubus/): Contains the transport implementations (HTTP RPC and Unix Socket), raw ubus message handling (blobmsg), results parsing, and error definitions.
• Base Layer (goubus/internal/base/): Provides generic, reusable implementations for standard ubus objects (e.g., system, network, uci). This layer encapsulates the common logic that applies to most OpenWrt devices.
• Profile Layer (goubus/profiles/): The public API entry point. Profiles (e.g., cmcc_rax3000m, generic) use Dialects to handle hardware-specific quirks (like parameter types or special method names) while exposing a consistent, high-level interface.
• Examples & TestData (examples/, internal/testdata/): Full integration tests using real hardware data and usage examples.

Comparison

Contributing & Device Support

This repository includes Profiles for RAX3000M and x86. The x86 Profile is derived from virtual machine data; given the diversity of x86 hardware and drivers, the implementation is undergoing further refinement.

Contributions of Profiles or testdata for other hardware are welcome.

How to help out

1. Copy: Copy profiles/x86_generic to a new folder.
2. Test: Run tests using your real hardware data to find parsing errors.
3. Fix: Use a Dialect to handle the differences.

Guide on how to dump test data: Contributing Test Data Guide.

License

MIT License - See LICENSE file for details.

Acknowledgments

Inspired by Kubernetes client-go and moby/moby.