Add NX-API JSON-RPC client and hack/nxapi helper

Introduce NXAPIClient in internal/provider/cisco/nxos/nxapi.go,
a thin HTTP client for the Cisco NX-OS NX-API JSON-RPC endpoint.

Add hack/nxapi, a minimal CLI that sends one or more NX-API
commands to a device and pretty-prints the JSON results.

Author: felix-kaestner

hack/nxapi/main.go

@@ -0,0 +1,105 @@
+// SPDX-FileCopyrightText: 2025 SAP SE or an SAP affiliate company and IronCore contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// nxapi is a minimal CLI tool for sending NX-API JSON-RPC commands to a
+// Cisco NX-OS device and printing the results.
+//
+// Usage:
+//
+//	go run ./hack/nxapi [flags] <cmd> [<cmd> ...]
+//
+// Example:
+//
+//	go run ./hack/nxapi -address 10.0.0.1:443 "show version" "show interface brief"
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/ironcore-dev/network-operator/internal/deviceutil"
+	"github.com/ironcore-dev/network-operator/internal/provider/cisco/nxos"
+)
+
+var fs = flag.NewFlagSet("nxapi", flag.ContinueOnError)
+
+func usage() {
+	fmt.Fprintf(os.Stderr, "Usage: nxapi [flags] <cmd> [<cmd> ...]\n\n")
+	fmt.Fprintf(os.Stderr, "Sends NX-API JSON-RPC commands to a Cisco NX-OS device.\n\n")
+	fmt.Fprintf(os.Stderr, "Flags:\n")
+	fs.PrintDefaults()
+	fmt.Fprintf(os.Stderr, "\nExample:\n")
+	fmt.Fprintf(os.Stderr, "  nxapi -address 10.0.0.1:8080 \"show version\" \"show interface brief\"\n")
+}
+
+func main() {
+	fs.Usage = usage
+
+	address := fs.String("address", "localhost:8080", "device address (host:port)")
+	username := fs.String("username", "admin", "NX-API username")
+	password := fs.String("password", "admin", "NX-API password")
+
+	if err := fs.Parse(os.Args[1:]); err != nil {
+		// flag.ContinueOnError: -h/--help prints usage and returns ErrHelp;
+		// other parse errors are already printed by the FlagSet.
+		return
+	}
+
+	cmds := fs.Args()
+	if len(cmds) == 0 {
+		fs.Usage()
+		os.Exit(1)
+	}
+
+	conn := &deviceutil.Connection{
+		Address:  *address,
+		Username: *username,
+		Password: *password,
+	}
+
+	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt /* == syscall.SIGINT */, syscall.SIGTERM)
+	defer cancel()
+
+	c, err := nxos.NewNXAPIClient(conn, 0)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		return
+	}
+
+	res, err := c.Do(ctx, nxos.NewRequest(cmds...))
+	if err != nil {
+		if errs, ok := errors.AsType[nxos.RPCErrors](err); ok {
+			for _, e := range errs {
+				fmt.Fprintf(os.Stderr, "RPC error %d: %s\n", e.Code, e.Message)
+				if len(e.Data) > 0 {
+					fmt.Fprintf(os.Stderr, "  data: %s\n", e.Data)
+				}
+			}
+			return
+		}
+		fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		return
+	}
+
+	for i, r := range res {
+		fmt.Printf("=== [%d] %s ===\n", i+1, cmds[i])
+		var pretty any
+		if err := json.Unmarshal(r, &pretty); err != nil {
+			fmt.Println(string(r))
+			continue
+		}
+		out, err := json.MarshalIndent(pretty, "", "  ")
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "error: failed to pretty-print JSON: %v\n", err)
+			fmt.Println(string(r))
+			continue
+		}
+		fmt.Println(string(out))
+	}
+}

internal/provider/cisco/nxos/nxapi.go

@@ -0,0 +1,254 @@
+// SPDX-FileCopyrightText: 2025 SAP SE or an SAP affiliate company and IronCore contributors
+// SPDX-License-Identifier: Apache-2.0
+
+package nxos
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"time"
+
+	"github.com/ironcore-dev/network-operator/internal/deviceutil"
+)
+
+// The RoundTripFunc type is an adapter to allow the use of
+// ordinary functions as [http.RoundTripper]. If f is a function
+// with the appropriate signature, RoundTripFunc(f) is a
+// [http.RoundTripper] that calls f.
+type RoundTripFunc func(*http.Request) (*http.Response, error)
+
+// RoundTrip returns f(r).
+func (f RoundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) {
+	return f(r)
+}
+
+// NXAPIClient sends JSON-RPC requests to a Cisco NX-OS device via NX-API.
+// Use [NewNXAPIClient] to construct one.
+type NXAPIClient struct {
+	client *http.Client
+	uri    string
+}
+
+// NewNXAPIClient creates a new [NXAPIClient] for the given connection.
+// If the connection has a TLS configuration set, HTTPS is used; otherwise HTTP.
+// The underlying HTTP client uses timeout for all requests; a value of 0
+// means no timeout.
+func NewNXAPIClient(c *deviceutil.Connection, timeout time.Duration) (*NXAPIClient, error) {
+	proto := "http"
+	if c.TLS != nil {
+		proto = "https"
+	}
+	uri, err := url.JoinPath(proto+"://"+c.Address, "ins")
+	if err != nil {
+		return nil, fmt.Errorf("nxapi: failed to join path: %w", err)
+	}
+	transport := http.DefaultTransport.(*http.Transport).Clone()
+	if c.TLS != nil {
+		transport.TLSClientConfig = c.TLS
+	}
+	return &NXAPIClient{
+		client: &http.Client{
+			Transport: RoundTripFunc(func(r *http.Request) (*http.Response, error) {
+				r.Header.Set("Content-Type", "application/json-rpc")
+				r.Header.Set("Cache-Control", "no-cache")
+				r.SetBasicAuth(c.Username, c.Password)
+				return transport.RoundTrip(r)
+			}),
+			Timeout: timeout,
+		},
+		uri: uri,
+	}, nil
+}
+
+// Do sends a Request to the device and returns one [json.RawMessage] per
+// command, in the same order as the request. If any command fails, Do returns
+// an [RPCErrors] containing one [RPCError] per failed command; transport and
+// HTTP errors are returned directly.
+func (c *NXAPIClient) Do(ctx context.Context, r Request) ([]json.RawMessage, error) {
+	b, err := r.Encode()
+	if err != nil {
+		return nil, fmt.Errorf("nxapi: failed to encode request: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.uri, bytes.NewReader(b))
+	if err != nil {
+		return nil, fmt.Errorf("nxapi: failed to create request: %w", err)
+	}
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("nxapi: failed to send request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("nxapi: failed to read response body: %w", err)
+	}
+
+	res, err := decode(body)
+	if err != nil {
+		return nil, fmt.Errorf("nxapi: failed to decode response: %w", err)
+	}
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		var errs RPCErrors
+		for _, r := range res {
+			if r.Error != nil {
+				errs = append(errs, r.Error)
+			}
+		}
+		if len(errs) == 0 {
+			return nil, &HTTPError{Code: resp.StatusCode, Body: body}
+		}
+		return nil, errs
+	}
+
+	msg := make([]json.RawMessage, len(res))
+	for i, r := range res {
+		msg[i] = r.Body.Data
+	}
+
+	return msg, nil
+}
+
+// Request is an ordered list of commands to send in a single JSON-RPC batch.
+type Request []cmd
+
+// NewRequest creates a Request from plain CLI command strings.
+func NewRequest(cmds ...string) Request {
+	r := make(Request, len(cmds))
+	for i, c := range cmds {
+		r[i] = cmd{
+			Jsonrpc: "2.0",
+			// Other possible values are "cli_ascii" and "cli_array".
+			// For now, we only support "cli" which is the default.
+			Method: "cli",
+			Params: params{
+				Cmd: c,
+				// Static NX-API version.
+				Version: 1,
+			},
+			ID: i + 1,
+		}
+	}
+	return r
+}
+
+// WithRollback sets the error action on each command in the request,
+// controlling what NX-OS does if that individual command fails.
+func (r Request) WithRollback(a ErrorAction) Request {
+	for i := range r {
+		r[i].Rollback = a
+	}
+	return r
+}
+
+// Encode serialises the request to JSON.
+func (r Request) Encode() ([]byte, error) {
+	return json.Marshal(r)
+}
+
+// cmd represents a single JSON-RPC command within a [Request].
+type cmd struct {
+	Jsonrpc  string      `json:"jsonrpc"`
+	Method   string      `json:"method"`
+	Params   params      `json:"params"`
+	ID       int         `json:"id"`
+	Rollback ErrorAction `json:"rollback,omitempty"`
+}
+
+// params holds the NX-API specific parameters for a [cmd].
+type params struct {
+	Cmd     string `json:"cmd"`
+	Version int    `json:"version"`
+}
+
+// ErrorAction controls how NX-OS responds when an individual command fails.
+type ErrorAction string
+
+const (
+	Stop     ErrorAction = "stop-on-error"
+	Continue ErrorAction = "continue-on-error"
+	Rollback ErrorAction = "rollback-on-error"
+)
+
+// res is the shared JSON-RPC response envelope.
+type res struct {
+	Error *RPCError `json:"error"`
+	Body  struct {
+		Data json.RawMessage `json:"body"`
+	} `json:"result"`
+}
+
+// decode attempts to parse the response body as either a single JSON-RPC response
+// or a batch of responses, returning a slice of [res] values in either case.
+func decode(body []byte) ([]res, error) {
+	if len(body) > 0 && body[0] == '{' {
+		var r res
+		if err := json.Unmarshal(body, &r); err != nil {
+			return nil, err
+		}
+		return []res{r}, nil
+	}
+	var r []res
+	if err := json.Unmarshal(body, &r); err != nil {
+		return nil, err
+	}
+	return r, nil
+}
+
+// RPCError represents a single JSON-RPC error returned by NX-OS.
+type RPCError struct {
+	// Code is the JSON-RPC error code.
+	Code int `json:"code"`
+	// Message is the human-readable error description.
+	Message string `json:"message"`
+	// Data contains additional error context as raw JSON, if present.
+	Data json.RawMessage `json:"data"`
+}
+
+func (e *RPCError) Error() string {
+	return fmt.Sprintf("nxapi: RPC error %d: %s", e.Code, e.Message)
+}
+
+// RPCErrors is a slice of [RPCError] values returned when one or more commands
+// in a request fail. It implements the error interface.
+type RPCErrors []*RPCError
+
+// Error implements the built-in error interface.
+func (e RPCErrors) Error() string {
+	errs := make([]error, len(e))
+	for i, err := range e {
+		errs[i] = err
+	}
+	return errors.Join(errs...).Error()
+}
+
+// Unwrap returns the individual RPC errors for use with errors.Is and errors.As.
+func (e RPCErrors) Unwrap() []error {
+	errs := make([]error, len(e))
+	for i, err := range e {
+		errs[i] = err
+	}
+	return errs
+}
+
+// HTTPError is returned when the NX-API endpoint responds with a non-2xx
+// status and the body cannot be parsed as a JSON-RPC error.
+type HTTPError struct {
+	// Code is the HTTP status code.
+	Code int
+	// Body contains the raw response body.
+	Body []byte
+}
+
+func (e *HTTPError) Error() string {
+	return fmt.Sprintf("nxapi: non-2xx status code: %d - %s", e.Code, string(e.Body))
+}