Overview

This repository is the companion to the article series Advanced NestJS Microservices covering building a custom NestJS microservice transporter.

Get the code

Get the repository by cloning [email protected]:johnbiundo/nestjs-faye-transporter-sample.git

$ # from the parent directory of where you want the project
$ git clone [email protected]:johnbiundo/nestjs-faye-transporter-sample.git transporter-tutorial

This clones the repository, which will grow to have multiple folders over the lifetime of the tutorial into a folder called transporter-tutorial (choose whatever name you like for this folder, but we'll reference this as the parent folder for the tutorial).

Repository Structure

The repository is structured with multiple branches, each corresponding to an article in the series.

Branch	Article Link
part1	Part 1: Introduction and Setup
part2	Part 2: Basic Server Component
part3	Part 3: Completing the Server Component
part4	Part 4: Basic Client Component
part5	Part 5: Completing the Client Component
(no new code)	Part 6: Survey of Built-in Transporters

Part 1: Introduction and Setup

This section corresponds to Part 1 of the series, and provides instructions for building and running the code in that section.

Checkout the Branch

For this section, you should be on branch part1:

$ # from the root folder (that you cloned into above)
$ git checkout part1
$ # build the artifacts
$ # note that this is a shell script so you may have to make adjustments
$ # if you're not on Linux, or fall back to running the individual
$ # `npm install` commands in each sub-directory
$ sh build.sh

Running the Code

The most useful exercise is to run the various components in multiple terminal windows: the Faye broker in one terminal, the customerApp native app in a second and the customerService native app in a third. As mentioned, tmux is a great fit for this, but you can just run 3 separate terminals or tabs if you so desire.

Terminal 1: run the Faye broker.

$ # from faye-server directory
$ npm run start

This starts the Faye broker and displays its log, which you can use to observe the message traffic.

Terminal 2: run the customerService native app.

$ # from customerService directory
$ npm run start

This starts the customerService native app, which runs as a background server, and displays its log so you can monitor message traffic.

Terminal 3: run the customerApp native app.

This is a "command line" app where you can issue a command that sends a request to the customerService app via the Faye broker.

Here's an example of the commands you can issue. These commands have been packaged as NPM scripts to make it easy to run them.

$ # from customerApp directory
$ npm run get-customers
$ # npm run get-customers is an alias that runs `node dist/customerApp.js get`
$
$ # view the response
$ npm run add-customer "Nike, Inc."
$ #  npm run add-customer is an alias that runs `node dist/customerApp.js add`
$
$ npm run get-customers
$ # view the updated response

Here's what it looks like with three tmux panes stacked vertically.

Part 2: Basic Server Component

This section corresponds to Part 2 of the series, and provides instructions for building and running the code in that section.

Checkout the Branch

For this part, you should be on branch part2:

$ # from the root folder (that you cloned into above)
$ git checkout part2
$ # build the artifacts
$ # note that this is a shell script so you may have to make adjustments
$ # if you're not on Linux, or fall back to running the individual
$ # `npm install` commands in each sub-directory
$ sh build.sh

The article contains instructions for running various requests.

Part 3: Completing the Server Component

This section corresponds to Part 3 of the series, and provides instructions for building and running the code in that section.

Checkout the Branch

For this part, you should be on branch part3:

$ # from the root folder (that you cloned into above)
$ git checkout part3
$ # build the artifacts
$ # note that this is a shell script so you may have to make adjustments
$ # if you're not on Linux, or fall back to running the individual
$ # `npm install` commands in each sub-directory
$ sh build.sh

At the end of this article, because we provided the nestHttpApp and a fully implementation of the Faye flavored ClientProxy, you now have a fully working Faye Custom Transporter.

You can test this end to end by issuing HTTP requests to the nestHttpApp like these (shown as HTTPie requests, but use your preferred client):

$ # Run the `GET /customers` request
$ http get localhost:3000/customers

$ # Run the `POST /customer` request to add a customer
$ http post localhost:3000/customer name="Acme, Inc."

Run the GET /customers request again to see it return the new customer.

With the verbose logging in place, it can be very helpful to observe the flow of messages between each of the active components in this setup to cement your understanding of how the pieces fit together.

Observables Side Trip

In the article we make reference to a deep dive on handling observables. You can check out that deep dive here any time you want. I encourage you to at least read the first section.

Part 4: Initial Client Component

This section corresponds to Part 4 of the series, and provides instructions for building and running the code in that section.

Checkout the Branch

For this part, you should be on branch part4:

$ # from the root folder (that you cloned into above)
$ git checkout part4
$ # build the artifacts
$ # note that this is a shell script so you may have to make adjustments
$ # if you're not on Linux, or fall back to running the individual
$ # `npm install` commands in each sub-directory
$ sh build.sh

The article provides instructions for running various tests.

Part 5: Final Client Component

This section corresponds to Part 5 of the series, and provides instructions for building and running the code in that section.

Checkout the Branch

For this part, you should be on branch part5:

$ # from the root folder (that you cloned into above)
$ git checkout part5
$ # build the artifacts
$ # note that this is a shell script so you may have to make adjustments
$ # if you're not on Linux, or fall back to running the individual
$ # `npm install` commands in each sub-directory
$ sh build.sh

At the end of this article, you have a complete, fully functional Faye transporter. You should be able to run any of the routes successfully. Refer above to the previous sections for various samples, such as Part 3. You can also explore the routes presented in the nestHttpApp controller, and run each of these. This page also presents some interesting advanced test cases (which are present in the routes in this branch).