Profile
Back to NewsBack
GitHub Trending 5 min
Reader Mode
ConnectEverything/nats-by-example: Collection of runnable, reference examples using NATS (https://nats.io)

ConnectEverything/nats-by-example: Collection of runnable, reference examples using NATS (https://nats.io)

NATS By Example

A collection of reference examples using NATS.

See https://natsbyexample.com to start exploring. Check out the 6m intro video to learn how to best use this resource.

Motivation

The vast majority of code examples that exist today don't work due to being incomplete or having invalid syntax OR the person trying to run the example doesn't know to properly setup the environment and/or dependencies for the example to run properly.

There are three primary goals of this repo:

  • Provide fully functional and robust reference examples for as many NATS
  • Sufficiently document each example and make them presentable for learning
  • Keep the examples up-to-date

Getting started

The recommended way to get started is to browse the website which provides nicer navigation and presentation for the example code in this repo.

When you want to actually execute the example code, you need to:

Pre-requisite requirement: currently the nbe CLI needs Docker and Compose (v2+) to work. It runs a set of containers hosting the CLI client and the NATS server. Other container runtimes would be considered if requested (such as Podman). Install Docker and Compose (if you do not have them installed).

  1. Clone this repository.
  2. Download the nbe CLI and extract the binary to the root of the cloned repository.
  3. Run the command with an example you want to try at the root of the repo:
$ nbe run messaging/pub-sub/cli
This will run the NATS CLI implementation of the core publish-subscribe example in a set of containers.

If everything is ok, you will see this output in console (timestamp will be different):

09:17:59 Published 5 bytes to "greet.joe" 
09:17:59 Subscribing on greet.* 
09:18:00 Published 5 bytes to "greet.joe"

[1] Received on "greet.joe" hello

[2] Received on "greet.pam"

The name of the example corresponds to the directory structure under examples/, specifically //.

Have questions, issues, or suggestions? Please open start a discussion or open an issue.

Status

In addition to the repo Issues there is a spreadsheet available in the Synadia shared Google Drive, NATS By Example - TODO

Design

Directory structure

Under the examples directory, each category has one or more examples with one or more client implementations. For example:

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

Meta files

The top-level meta.yaml is used to define the order of the categories.

# Ordered set of categories.
categories: [string]

The category meta.yaml supports the following properties:

# Title of the category, defaults to a titlecase of the directory name.
title: string

Description of the category.

description: string

An ordered list of the example names within the category.

examples: [string]

The example meta.yaml supports the following properties:

# Title of the example, defaults to the title-case of the directory name.
title: string

Description of the example.

description: string

Client directory

The directory is named after the NATS client they correspond to, either the language name, e.g. go or the CLI, e.g. cli. For multi-client examples or ones requiring complex setups, the directory can be named shell to indicate a custom shell script is being used.

The entrypoint file is expected to be named main.[ext] where the ext is language specific or sh for a shell script (including CLI usage). In addition to convention, the significance of this file is that the comments will be extracted out to be rendered more legibly alongside the source code for the website.

Each client may include a custom Dockerfile to be able to build and run the example in a container acting as a controlled, reproducible environment. If not provided, the default one, by language, in the docker/ directory will be used.

Most examples require a NATS server, so there are two docker-compose.yaml files available in docker/ which will be used by default. If there is a need for a customer file for an example, it can be added to the example directory to override the default.

Verifying examples

nbe verify builds and runs examples and checks that they still work: an example fails if it doesn't build, exits non-zero or times out, and warns if its output is empty, shows new errors, or drifted from the committed output.txt.

$ nbe verify go                      # every Go example
$ nbe verify 'messaging/*/rust'      # a glob
$ nbe verify --out /tmp/out all      # everything, keeping new outputs
$ nbe verify --record kv/intro/go    # re-record output.cast/output.txt

The verify-examples workflow runs this monthly for all examples (tracked in an issue labelled example-health) and on pull requests for the examples they touch. Dependency updates come from Dependabot; see the upgrade guide for upgrading by hand.

Contributing

There are several ways to contribute!

  • Create an issue for an issue with an existing example (comment or code)
  • Create an issue to for a new client of an existing example
  • Create an issue to recommend a new example
  • Create a pull request to fix an existing example
  • Create a pull request for a new client of an existing example
Chat with me