Chains

What Is a Chain?

In the context of Drash, a chain is a set of handlers that are connected together to form a variant of the Chain of Responsibility pattern. Each handler receives an input and returns an output. Chains are responsible for:

  • connecting handlers together;
  • receiving inputs from clients;
  • sending inputs to handlers; and
  • returning outputs from handlers to clients.

In simplest form, their flow looks like the diagram below:

When you build HTTP applications with Drash, you start by creating a chain (specifically the Request Chain). From there, you give it resources. Resources are the classes you use to process requests and respond to those requests.

Where Is the Chain Placed?

TLDR

The chain is placed (by you) behind your chosen runtime's HTTP server. This is explained in more detail below.

Detailed Explanation

After you create a chain, you place it behind your chosen runtime's HTTP server so your chosen runtime's HTTP server can send HTTP requests to it. To visualize how the chain fits into the bigger picture of a system, we can start by looking at just the chain.

A system with just the chain looks like the following:

This chain is not useful unless it handles HTTP requests. To do that, it needs a runtime like Node, Deno, etc. It also needs to connect to the runtime's HTTP server.

Once it is connected to the runtime's HTTP server, the system looks like:

Still, this chain is not useful unless the runtime's HTTP server is running and listening for HTTP requests. Once the HTTP server is running, clients (e.g., browsers) will be allowed to make requests to the HTTP server.

When clients are making requests to the HTTP server, the system looks like:

Although the above system can be somewhat of a working system, it doesn't account for dynamic data (e.g., data retrieved from a service like Stripe or database like Postgres). In the real world, systems can connect to other services/systems for data.

A system that connects to other services/systems for data looks like:

As you can see above, "Some Service" is an API Endpoint that the Drash Chain is making requests to for data. In this system, clients could make requests to the API Endpoint through the runtime's HTTP server and Drash's chain.

What Data Does It Process?

The Shape of the Data

Drash's chains process the data you give it. This means you are in charge of defining what goes into the chain and what comes out. However, the data you give it must meet the following requirements:

  1. The data must be a single object
  2. The object must have a url: string property and it must be a fully qualified URL (examples below): 
    // Good
const url: string = "http://localhost:1447/accounts/1337";
 
// Bad
const url: string = "/accounts/1337";
  3. The object must have a method: string property and must be a valid HTTP request method (examples below): 
    // Uppercase is OK
const method: string = "GET";
 
// Lowercase is also OK
const method: string = "get";

Examples of Correct Data

Below is an example of what the object should look like at a minimum:

const minimal = {
  url: "http://localhost:1447/accounts/1337",
  method: "get",
};

In Node, you might find yourself using something like:

const context = {
  url: "http://localhost:1447/accounts/1337",
  method: "get",
  req: IncomingMessage { ... } // shortened for brevity
  res: ServerResponse { ... } // shortened for brevity
  // ...
  // ... add as many fields as you wish
  // ...
}

Data Exchange Summarized

In general, the data exchange in a system with a client, runtime, Drash chain, and some service looks like:

The above diagram is explained as follows:

  • The Client and Runtime exchange HTTP messages (opens in a new tab). This process is defined by the Client and Runtime.
  • The Runtime and Drash Chain exchange inputs and outputs. The data types of these inputs and outputs are defined by the Runtime and you. For example, if Runtime was Deno, then HTTP Server would give you a Request object (because Deno's HTTP Server gives you a Request object). When you get the Request object, you can pass it to your chain and have your chain return a Response object. That Response object is what you can pass to Deno's HTTP Server (since Deno's HTTP Server requires you to give it a Response object).
  • If Some Service exists, then the data type of the data being exchanged between Some Service and Drash Chain would be defined by Some Service.

Next Steps

Feel free to follow our recommendation, jump ahead, or navigate the documentation pages at your leisure.

Our Recommendations

Want to Jump Ahead?