Skip to content
Architect sdk supporting Node.js
TypeScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
dist
src
.gitignore
README.md
package-lock.json
package.json
tsconfig.json

README.md

Architect Node.js SDK

This is the Node.js SDK used for brokering connections to microservice dependencies via Architect's deployment platform. If you're unfamiliar with the platform or our deploy tools, please check out Architect.io and our CLI to get started.

SDK Documentation

Connecting to dependencies

import architect from '@architect-io/sdk';

const my_dependency = architect.service('my_dependency_name');

// Client used to connect to service
const client = my_dependency.client;

// Dynamically imported models used for message formatting
// Used by protocols supporting code-gen like gRPC
const defs = my_dependency.defs;

REST

The Architect SDK uses the popular REST client, Axios, to broker communication to downstream REST microservices. The client that is provided is an Axios instance that is enriched with the proper service location meaning only URIs and HTTP actions need be provided:

const axios_res = await my_dependency.client.get('/resource');
const axios_res = await my_dependency.client.post('/resource', { data });
const axios_res = await my_dependency.client.put('/resource/:resource_id', { data });
const axios_res = await my_dependency.client.delete('/resource/:resource_id');

gRPC

Architect handles the code-gen for gRPC services for you. Every time you run $ architect install ..., you'll find relevant gRPC stubs generated and placed inside an architect_services folder in your service's root directory. This SDK handles the import of generated model objects for parsing input/output messages as well as the import and enrichment of client code for making calls to dependencies.

// example.proto
syntax = "proto3";

package example_service;

message PayRequest {
    int32 amount = 1;
}

message PayResponse {
    int32 output = 1;
}

service Example {
  rpc Pay (PayRequest) returns (PayResponse) {}
}
// Model definitions will match message names in the .proto file for the service
const pay_req = my_dependency.defs.PayRequest();
pay_req.setAmount(10);

// Client will automatically have methods matching the service definition from 
// the dependency's .proto file. Response handling matches gRPC documentation.
my_dependency.client.pay(pay_req, (error, grpc_res) => {
  const output = grpc_res.getOutput();
});

Connecting to data stores

Since there are so many DB clients available, we don't want to choose a default for developers. Instead, the Architect SDK provides easy mechanics to parse credentials provided by the platform:

import architect from '@architect-io/sdk';
import {createConnection} from "typeorm";

// Key used to cite the datastore must match the key used in your 
// architect service config
const db_config = architect.datastore('primary_db');
const connection = await createConnection({
   type: "postgres",
   host: db_config.host,
   port: db_config.port,
   username: db_config.username,
   password: db_config.password,
   database: db_config.name
});

Events and messaging

The Architect platform also supports pub/sub based communication between services. The primary use-case for this flow would be to allow services to broadcast events for other services to subscribe to without needing to know who the subscribers are.

NOTE: As of v0.2.x of the SDK, the only method for publishing/subscribing to events using Architect is via REST (mirroring the function of traditional webhooks). We're actively working on means of supporting queuing systems like RabbitMQ, AWS SQS, and more.

Subscribing

// architect.json
{
  "subscriptions": {
    "<service_name>": {
      "<event_name>": {
        "uri": "/event/callback",
        "headers": {
          "x-custom-header": "example"
        }
      }
    }
  }
}

The URI used for registration must match a URI on your service:

import * as express from 'express';
import architect from '@architect-io/sdk';

const app = express();

app.post('/event/callback', (req, res) => {
  // Custom event handling here...
});

app.listen(process.env.PORT);

Publishing

NOTE: simple publication methods coming soon. For now, you can iterate through subscribers to submit events.

// architect.json
{
  "notifications": ["<event_name>"]
}
import * as axios from 'axios';
import architect from '@architect-io/sdk';

// Iterate through notification subscribers to POST payload
architect.notification('<event_name>').subscriptions.forEach(async (sub) => {
  const axios_instance = axios.create({
    baseURI: `${sub.host}:${sub.port}`,
    headers: sub.headers
  });
  await axios_instance.post(sub.uri, { payload });
});
You can’t perform that action at this time.