NATS By Example

The repository is organized by NATS concepts. Under the examples/ directory, examples are grouped into categories. Each example contains one or more client implementations (e.g., go, python, cli, or shell).

Structure Pattern: examples/<category>/<example>/<client>/main.[ext]

• Category: A high-level NATS concept (e.g., messaging).
• Example: A specific pattern or feature (e.g., pub-sub).
• Client: The language or tool used to implement the example (e.g., go, cli).
• Entrypoint: The file main.[ext] (e.g., main.go, main.sh) is the required entrypoint for the client.

examples/
  meta.yaml
  messaging/
    meta.yaml
    pub-sub/
      meta.yaml
      cli/
        main.sh
      go/
        main.go
      python/
        main.py

Each client directory in an example can define its own environment:

1. Entrypoint: The file must be named main.[ext] (e.g., main.go, main.py, main.sh).
2. Custom Dockerfile: If a client directory contains a Dockerfile, it will be used to build the container for that example. If not, the CLI uses the default language-specific Dockerfile from the docker/ directory.
3. Custom Docker Compose: If an example directory contains a docker-compose.yaml file, it will override the default NATS server configuration provided in the docker/ directory.

To execute a NATS example in a reproducible environment, use the nbe CLI. The CLI runs a set of containers hosting both the NATS server and the specific client implementation for the example.

Prerequisites

• Docker and Docker Compose (v2+).
• The nbe binary downloaded from the releases page and placed in the root of the cloned repository.

Execution

Run the command from the root of the repository using the path to the example following the pattern <category>/<example>/<client>.

Example: To run the NATS CLI implementation of the core publish-subscribe example:

$ nbe run messaging/pub-sub/cli

The documentation generator uses several internal data structures to map the repository's example hierarchy into HTML pages. These structures represent the relationship between categories, examples, and specific language implementations (clients).

• indexData: Represents the root index page, containing a list of indexCategory objects.
• indexCategory: A grouping of examples under a specific title and description.
• categoryData: Represents a category-specific landing page.
• exampleData: Represents the landing page for a specific NATS example, containing links to various language implementations.
• clientData: The most granular level, representing a specific language implementation of an example (e.g., the Go version of a 'Pub/Sub' example). It includes source code, rendered blocks, and execution output.

The nbe CLI tool manages a compatibility matrix for NATS examples. It ensures that various client libraries (Go, Python, Node, Rust, etc.) work correctly across different versions of the NATS Server and the NATS CLI.

Internally, the tool uses YAML configuration files to define:

1. Versions: Specific versions for the NATS Server, CLI, and various client languages.
2. Matrix: A set of version combinations that must be tested to ensure compatibility.

When running the matrix, the tool automates the process of updating dependency files (like go.mod, package.json, requirements.txt, or Cargo.toml) within example directories, building Docker images, and running the examples via Docker Compose to verify they pass (returning OK) or fail (returning ERR).

The documentation engine processes raw example files into formatted HTML using two main mechanisms:

1. Code Blocks: Uses the chroma library for syntax highlighting. It maps specific language names to appropriate lexers (e.g., Deno is treated as ts, WebSocket as js).
2. Comment Blocks: Extracts comments from source files, cleans them of leading whitespace and comment delimiters (like // or /* */), and renders the remaining text as Markdown using blackfriday.

Results are encapsulated in the RenderedBlock struct, which specifies whether the content is code or comment and provides the resulting HTML.

An Example represents a specific NATS pattern and contains a map of Clients. Each Client represents a specific language implementation of that example. A Client includes:

• Language: The identifier for the SDK (e.g., go, python).
• MainFile: The entry point file (e.g., main.go, main.py).
• Blocks: A collection of Block objects representing segments of code or comments.
• Source: The full raw source code string.

The parser divides source code into Block types to distinguish between different types of content. This allows the system to treat code and comments differently when rendering or processing examples.

Supported BlockType values:

• EmptyBlock: Initial state.
• BreakBlock: A boundary marker.
• CodeBlock: Actual executable code.
• SingleLineCommentBlock: Comments starting with //, #, etc.
• MultiLineCommentBlock: Comments wrapped in /* ... */ or /** ... */.

Special boundary marker: The parser recognizes <!break> at the end of a line as a BreakLine to explicitly separate blocks.