NUI Documentation

All messages exchanged between the client and the server via WebSockets follow a standardized wrapper structure. Every message must include a type string to identify the message purpose and a payload containing the actual data associated with that type.

{
  "type": string,
  "payload": any // based on type
}

A Subscription entity is used to bookmark favorite NATS subjects. This allows a user to subscribe to core NATS messages for a specific subject. The entity consists of a single subject property which is a string representing the NATS subject to be monitored.

Subscription {
	subject: string
}

The nats object in the metrics payload maps directly to NATS server monitoring endpoints. It is divided into two primary sections:

• varz: Server-wide statistics including configuration, uptime, memory usage, and NUI-specific throughput metrics (e.g., nui_in_bytes_sec).
• connz: Connection-specific statistics, providing details on client connections and their individual activity.

The NATS UI protobuf decoder includes several automated features to simplify message inspection:

• Topic pattern learning: The system learns patterns from NATS subjects. For example, a message on user.123.events.created will be mapped to the pattern user.*.events.created.
• Persistent caching: Successful schema/message type combinations are remembered for future use.
• Import resolution: The decoder automatically handles dependencies between .proto files.
• Google types support: Common Google protobuf types like google.protobuf.Timestamp, Any, and Duration are supported out of the box.

The response for the KV index endpoint is an array of kv-entry objects.

Important Limitation: In the response from this specific index endpoint, both the value and history properties of each kv-entry are set to null. To retrieve the actual data stored at a key, you must use the full entry API.

kv-entry[] // value and history are null in index

A Connection in NUI manages one or more underlying NATS server connections. It encapsulates connection details including hosts, authentication methods, TLS settings, metrics configuration, and a list of bookmarked subscriptions.

Key properties include:

• name: A unique identifier for the connection.
• hosts: An array of NATS server addresses.
• status: The current connection state, represented by CNN_STATUS.

Connection {
	id?: string
	name: string
	hosts: string[]
	inboxPrefix: string
	subscriptions: Subscription[]
	auth: Auth[]
	tls_auth: TLSAuth
	metrics: Metrics
	status?: CNN_STATUS
}

// Connection Statuses
// CONNECTED, RECONNECTING, DISCONNECTED, or UNDEFINED

A CliImport is a Nui connection type used to manage one or more underlying NATS server connections. It represents the metadata and context associated with an import operation performed via the CLI.

CliImport
{
    name: string
    path: string
    error: string
    importedContext: { [key: string]: any }
}

To delete a specific stream, send a DELETE request to the API endpoint. You must provide the unique identifier for the connection containing the stream and the name of the stream you wish to remove. This operation does not require a request body and returns a 204 status code upon successful deletion.

DELETE /api/connection/:connection_id/stream/:stream_name

Once your schemas are in the correct directory, follow these steps to view decoded data:

1. Open a binary message in NATS UI.
2. Select "Protobuf" from the formatter dropdown menu.
3. The system will attempt to auto-detect the schema and message type. If successful, you will see the decoded JSON data.

Note: If auto-detection fails, you can manually select the correct schema and message type from the UI.

NUI uses Go for the backend and React with Vite for the frontend. To build and run the project locally, ensure you have the following prerequisites installed:

Prerequisites:

• Go 1.21
• Node 18
• Wails.io

Running the Web App

To start the application in web mode, use the following commands. This mode uses the db directory as a persistent data directory:

npm install
make dev-web

Running the Desktop App

To start the application in development mode using Wails (building for your underlying operating system):

make dev

# Web app
npm install
make dev-web

# Desktop app
make dev

To establish a subscription to a specific WebSocket connection, perform a GET request to the /ws/sub endpoint, providing the id of the connection as a query parameter.

GET /ws/sub?id=<connection-id>

To create a new Key-Value (KV) bucket, send a POST request to the KV endpoint for a specific connection. You must provide a connection_id in the URL and a bucket_config object in the request body.

Endpoint: POST /api/connection/:connection_id/kv

Parameters:

• connection_id: The UUID of the connection on which the bucket will be created.

Request Body:

• bucket_config: A configuration object defining the bucket's properties (see BUCKET-CONFIG for details).

Response:

• Returns a stream_state object representing the state of the bucket (see BUCKET-STATE for details).

POST /api/connection/:connection_id/kv

// Body
{
  "bucket_config": { ... }
}