func (Body) Bytes ¶

func (b Body) Bytes() ([]byte, error)

Bytes returns the JSON byte slice representation and any error encountered during building

This is useful when you need []byte instead of string for efficiency.

Example:

body := gnmi.Body{}.Set("name", "eth0")
jsonBytes, err := body.Bytes()
if err != nil {
    log.Fatal(err)
}

func (Body) Delete ¶

func (b Body) Delete(path string) Body

Delete removes a value at the specified JSON path and returns a new Body

The path uses dot notation for nested fields (e.g., "config.description").

If an error occurs, the error is stored and returned by String() or Err().

Example:

body := gnmi.Body{}.
    Set("name", "eth0").
    Set("description", "temp").
    Delete("description")  // Remove description field
json, err := body.String()

Returns the Body for method chaining.

func (Body) Err ¶

func (b Body) Err() error

Err returns any error that occurred during the building process

This method allows checking for errors without retrieving the string value.

Example:

body := gnmi.Body{}.Set("config.hostname", "router1")
if err := body.Err(); err != nil {
    log.Fatal(err)
}

func (Body) Res ¶

func (b Body) Res() string

Res returns the JSON string for further processing with gjson

This allows you to query the built JSON using gjson's Get function. If an error occurred during building, this returns an empty string. Use Err() or String() to check for errors.

Example:

body := gnmi.Body{}.Set("config.hostname", "router1")
if body.Err() == nil {
    json := body.Res()
    hostname := gjson.Get(json, "config.hostname").String()
}

Returns the JSON string that can be queried with gjson.Get.

func (Body) Set ¶

func (b Body) Set(path string, value any) Body

Set sets a value at the specified JSON path and returns a new Body

The path uses dot notation for nested fields (e.g., "config.name"). The value can be any type that sjson supports (string, number, bool, etc.).

If an error occurs, the error is stored and returned by String() or Err(). Once an error occurs, all subsequent operations are no-ops that preserve the error.

Example:

body := gnmi.Body{}.
    Set("config.name", "eth0").
    Set("config.enabled", true).
    Set("config.mtu", 1500)
json, err := body.String()

Returns the Body for method chaining.

func (Body) String ¶

func (b Body) String() (string, error)

String returns the JSON string representation and any error encountered during building

This method returns both the JSON string and any error that occurred during the building process. If an error occurred during any Set/Delete operation, the error will be returned here.

Example:

body := gnmi.Body{}.Set("config.hostname", "router1")
json, err := body.String()
if err != nil {
    log.Fatal(err)
}

func (*Client) Backoff ¶

func (c *Client) Backoff(attempt int) time.Duration

Backoff calculates the backoff delay for retry attempt using exponential backoff with jitter

The formula is: delay = min(minDelay * (factor ^ attempt) + jitter, maxDelay) where jitter is a cryptographically secure random value in [0, delay * 0.1].

Security Note: Uses crypto/rand for jitter to prevent timing attack predictability. If crypto/rand fails, falls back to timestamp-based jitter to prevent thundering herd. Timestamp-based jitter is not cryptographically secure but provides sufficient randomness for retry dispersal.

Parameters:

• attempt: The retry attempt number (0-indexed)

Returns the duration to wait before retrying.

func (*Client) Capabilities ¶

func (c *Client) Capabilities(ctx context.Context) (CapabilitiesRes, error)

Capabilities retrieves the gNMI server capabilities

This operation performs a gNMI Capabilities RPC to discover:

• gNMI service version
• Supported encodings (json, json_ietf, proto, etc.)
• Supported data models

The capabilities are stored in the client for later reference. Use HasCapability() to check for specific capabilities.

Example:

ctx := context.Background()
res, err := client.Capabilities(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("gNMI version: %s\n", res.Version)
for _, cap := range res.Capabilities {
    fmt.Printf("Encoding: %s\n", cap)
}

func (*Client) Close ¶

func (c *Client) Close() error

Close closes the gNMI session and cleans up resources (terminal operation).

This method is TERMINAL - the client cannot be reused after calling Close(). All resources are released and the target configuration is destroyed.

Use Disconnect() instead if you want to temporarily close the connection while preserving the ability to reconnect later.

This method is typically used in defer statements to ensure proper cleanup:

Example:

client, err := gnmi.NewClient("192.168.1.1:57400", opts...)
if err != nil {
    log.Fatal(err)
}
defer client.Close() // Ensure cleanup on function exit

// Use client...
res, err := client.Get(ctx, paths)

Thread-safe: safe to call multiple times (subsequent calls are no-ops).

func (*Client) Disconnect ¶

func (c *Client) Disconnect() error

Disconnect closes the gRPC connection but preserves client configuration.

Unlike Close(), this method allows the client to be reused - subsequent operations will automatically reconnect. This is useful for:

• Connection pooling with idle timeout disconnection
• Long-running applications that need to release connections temporarily
• Testing reconnection logic

The client maintains its target configuration and will reconnect on the next RPC call via the ensureConnected() mechanism.

Example - Disconnect and reuse pattern:

client, _ := gnmi.NewClient("192.168.1.1:57400", opts...)
defer client.Close()

// Use client
_, err := client.Get(ctx, paths)

// Release connection temporarily
client.Disconnect()

// Automatically reconnects on next use
_, err = client.Get(ctx, paths)

Example - Connection pooling with idle timeout:

// Disconnect idle connections periodically
ticker := time.NewTicker(5 * time.Minute)
go func() {
    for range ticker.C {
        client.Disconnect() // Release idle connection
    }
}()

Example - Long-running application pattern:

// Disconnect during maintenance window
client.Disconnect()
performMaintenance()
// Reconnects automatically when needed
client.Get(ctx, paths)

Thread-safe: safe for concurrent use with other client methods.

func (*Client) Get ¶

func (c *Client) Get(ctx context.Context, paths []string, mods ...func(*Req)) (GetRes, error)

Get performs a gNMI Get operation to retrieve data from the device

Get supports querying multiple paths in a single request. The paths parameter must be a non-empty slice of gNMI path strings. The encoding can be specified via request modifiers, defaulting to json_ietf.

The operation uses RLock for concurrent read access, allowing multiple Get operations to run in parallel. Context timeout follows priority:

1. Request-specific timeout (via Timeout modifier)
2. Context deadline (if already set)
3. Client.OperationTimeout (fallback default)

Example:

ctx := context.Background()
paths := []string{
    "/interfaces/interface[name=GigabitEthernet0/0/0/0]/state",
    "/system/config/hostname",
}
res, err := client.Get(ctx, paths)
if err != nil {
    log.Fatal(err)
}
for _, notif := range res.Notifications {
    fmt.Printf("Path: %s\n", notif.Prefix)
}

Returns GetRes with notifications, timestamp, OK status, and any errors.

func (*Client) HasCapability ¶

func (c *Client) HasCapability(capability string) bool

HasCapability checks if the server supports a specific capability

Example:

if client.HasCapability("gnmi-1.0") {
    // Use gNMI 1.0 features
}

func (*Client) HasCredentials ¶

func (c *Client) HasCredentials() bool

HasCredentials returns true if credentials are configured

This method only indicates if credentials exist without exposing the actual values.

Example:

if client.HasCredentials() {
    fmt.Println("Client is configured with credentials")
}

func (*Client) Ping ¶

func (c *Client) Ping(ctx context.Context) error

Ping verifies connectivity by performing a Capabilities RPC

This method establishes a connection if not already connected and performs a gNMI Capabilities request to verify the server is reachable and responsive. This is useful when you want to explicitly verify connectivity before performing other operations.

Example:

client, err := gnmi.NewClient("192.168.1.1:57400", opts...)
if err != nil {
    log.Fatal(err)  // Configuration error
}
defer client.Close()

// Verify connection before proceeding
if err := client.Ping(ctx); err != nil {
    log.Fatal(err)  // Connection error
}

// Now confident connection works
res, err := client.Get(ctx, paths)

func (*Client) ServerCapabilities ¶

func (c *Client) ServerCapabilities() []string

ServerCapabilities returns the list of capabilities supported by the server

Returns a copy of the capabilities slice to prevent external modification.

Example:

caps := client.ServerCapabilities()
for _, cap := range caps {
    fmt.Println(cap)
}

func (*Client) Set ¶

func (c *Client) Set(ctx context.Context, ops []SetOperation, mods ...func(*Req)) (SetRes, error)

Set performs a gNMI Set operation to configure the device

Set supports multiple update, replace, and delete operations in a single request. The ops parameter must be a non-empty slice of SetOperation structs created via the Update(), Replace(), or Delete() helper functions.

The operation uses Lock for exclusive write access, serializing all Set operations to prevent concurrent writes. Context timeout follows priority:

1. Request-specific timeout (via Timeout modifier)
2. Context deadline (if already set)
3. Client.OperationTimeout (fallback default)

Example:

ctx := context.Background()
ops := []gnmi.SetOperation{
    gnmi.Update("/interfaces/interface[name=Gi0/0/0/0]/config/description",
        `{"description": "WAN Interface"}`),
    gnmi.Replace("/interfaces/interface[name=Gi0/0/0/0]/config/enabled",
        `{"enabled": true}`),
    gnmi.Delete("/interfaces/interface[name=Gi0/0/0/1]/config"),
}
res, err := client.Set(ctx, ops)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Set operation successful: %v\n", res.OK)

Returns SetRes with response, timestamp, OK status, and any errors.

func (*DefaultLogger) Debug ¶

func (l *DefaultLogger) Debug(ctx context.Context, msg string, keysAndValues ...any)

Debug logs a debug message with structured key-value pairs

func (*DefaultLogger) Error ¶

func (l *DefaultLogger) Error(ctx context.Context, msg string, keysAndValues ...any)

Error logs an error message with structured key-value pairs

func (*DefaultLogger) Info ¶

func (l *DefaultLogger) Info(ctx context.Context, msg string, keysAndValues ...any)

Info logs an informational message with structured key-value pairs

func (*DefaultLogger) Warn ¶

func (l *DefaultLogger) Warn(ctx context.Context, msg string, keysAndValues ...any)

Warn logs a warning message with structured key-value pairs

func (GetRes) GetValue ¶

func (r GetRes) GetValue(path string) gjson.Result

GetValue retrieves a value from the response notifications using a gjson path. The path follows gjson syntax for querying JSON structures.

Example paths:

• "notification.0.timestamp" - Get notification timestamp
• "notification.0.update.0.path.elem.0.name" - Get path element name
• "notification.0.update.0.val.Value.JsonIetfVal" - Get JSON IETF value (base64 encoded)

Note: The JSON structure uses protobuf JSON marshaling conventions where field names are lowercase and TypedValue.Value is nested with capitalized names.

Returns gjson.Result which can be converted to specific types:

• result.String() for string values
• result.Int() for integer values
• result.Bool() for boolean values
• result.Array() for array values

Example:

res, err := client.Get(ctx, []string{"/interfaces/interface[name=Gi0/0/0/0]/state"})
if err != nil {
    log.Fatal(err)
}
timestamp := res.GetValue("notification.0.timestamp").Int()
pathName := res.GetValue("notification.0.update.0.path.elem.0.name").String()

// This example shows how to use GetValue with gjson paths
notification := &gnmi.Notification{
	Timestamp: 1234567890,
	Update: []*gnmi.Update{
		{
			Path: &gnmi.Path{
				Elem: []*gnmi.PathElem{
					{Name: "system"},
					{Name: "config"},
				},
			},
			Val: &gnmi.TypedValue{
				Value: &gnmi.TypedValue_JsonIetfVal{
					JsonIetfVal: []byte(`{"hostname": "router1"}`),
				},
			},
		},
	},
}

res := GetRes{
	Notifications: []*gnmi.Notification{notification},
	Timestamp:     1234567890,
	OK:            true,
}

// Get the JSON value
jsonValue := res.GetValue("notification.0.update.0.val.json_ietf_val").String()
_ = jsonValue // Use the value

func (GetRes) JSON ¶

func (r GetRes) JSON() string

JSON returns the response notifications as a formatted JSON string. This is useful for debugging, logging, or custom parsing. Returns an empty string if marshaling fails.

Example:

res, err := client.Get(ctx, []string{"/system/config"})
if err != nil {
    log.Fatal(err)
}
fmt.Println(res.JSON()) // Print full response as JSON

func (*GnmiError) DetailedError ¶

func (e *GnmiError) DetailedError() string

DetailedError returns the full error message including internal details

This should only be used in secure logging contexts where sensitive information disclosure is acceptable (e.g., server-side logs, debug output).

Example:

if err != nil {
    if gnmiErr, ok := err.(*GnmiError); ok {
        log.Debug(gnmiErr.DetailedError()) // internal logging
        return gnmiErr.Error() // client-facing error
    }
}

func (*GnmiError) Error ¶

func (e *GnmiError) Error() string

Error implements the error interface

func (LogLevel) String ¶

func (l LogLevel) String() string

String returns the string representation of a LogLevel

func (*NoOpLogger) Debug ¶

func (n *NoOpLogger) Debug(_ context.Context, _ string, _ ...any)

Debug discards the log message

func (*NoOpLogger) Error ¶

func (n *NoOpLogger) Error(_ context.Context, _ string, _ ...any)

Error discards the log message

func (*NoOpLogger) Info ¶

func (n *NoOpLogger) Info(_ context.Context, _ string, _ ...any)

Info discards the log message

func (*NoOpLogger) Warn ¶

func (n *NoOpLogger) Warn(_ context.Context, _ string, _ ...any)

Warn discards the log message

func (SetRes) GetValue ¶

func (r SetRes) GetValue(path string) gjson.Result

GetValue retrieves a value from the SetResponse using a gjson path. The path follows gjson syntax for querying JSON structures.

Example paths:

• "response.0.op" - Get operation type (UPDATE, REPLACE, DELETE)
• "response.0.path" - Get path string
• "timestamp" - Get response timestamp

Returns gjson.Result which can be converted to specific types:

• result.String() for string values
• result.Int() for integer values

Example:

ops := []gnmi.SetOperation{
    gnmi.Update("/interfaces/interface[name=Gi0/0/0/0]/config/mtu", `{"mtu": 9000}`),
}
res, err := client.Set(ctx, ops)
if err != nil {
    log.Fatal(err)
}
op := res.GetValue("response.0.op").String()

func (SetRes) JSON ¶

func (r SetRes) JSON() string

JSON returns the SetResponse as a formatted JSON string. This is useful for debugging, logging, or custom parsing. Returns an empty string if marshaling fails.

Example:

ops := []gnmi.SetOperation{
    gnmi.Update("/system/config/hostname", `{"hostname": "router1"}`),
}
res, err := client.Set(ctx, ops)
if err != nil {
    log.Fatal(err)
}
fmt.Println(res.JSON()) // Print full response as JSON