Skip to main content

Internal message

1. Overview#

It is important to have a unified language for communication between services, especially for hybrid architecture. CellularJS's internal message is not built from scratch, instead it is based on interface of a well-known protocol - HTTP.

Just to clarify, internal message is not HTTP message, it is made out of HTTP message. You can consider internal message as a DTO with HTTP-like structure.

2. Internal request#

note

CellularJS can work well with HTTP but it is a protocol-agnostic framework. It has nothing called session, cookie. If you want to use it, please map it into internal message header, or even body.

2.1. Request header#

Request header is an object. You can define any header but there are some reserved headers you should known.

2.1.1. to#

to is used for routing request. It includes a cell name and a service name separated by a colon(Eg: 'Mailer:SendMail', 'Auth:SignIn').

2.1.2. referer#

referer(optional) is the name of the cell and service that current request come from(Eg: 'User:GetInfo'). You will need this header when sending request across cells.

2.2. Request body#

Request body contain request data and this data must be well-known data.
Default value: {}

2.3. Example#

Example 1: Create internal request.

import { IRQ } from '@cellularjs/net';
// IRQ to get logged in user info:const getUserInfoIrq = new IRQ({  to: 'User:Me',  token: '**.******.**',});
// IRQ for file uploading:const uploadFilesIrq = new IRQ(  {    to: 'Media:PushObjects',    token: '**.******.**',  },  { objs: [] },);

Example 2: Get current internal request in callee with dependency injection.

import { IRQ, Service, ServiceHandler } from '@cellularjs/net';

@Service({ scope: 'publish' })export class SignIn implements ServiceHandler {  constructor(    private irq: IRQ,  ) { }
  handle() {    const { irq } = this;
    console.log(irq.body.username);    console.log(irq.body.password);    // ...  }}
tip

For request validation, let have a look at this article

3. Internal response#

3.1. Response header#

Like request header, response header is an object. You can define any header but there are some reserved headers in CellularJS too.

3.1.1. Status#

status is an integer, it includes the 3 first digits and extended status(optional).

The 3 first digits: It has similar meaning to HTTP status code.

  • 1xx: Informational response(placeholder).
  • 2xx: Success response.
  • 3xx: Redirection(placeholder).
  • 4xx: Error response, caused by caller.
  • 5xx: Error response, caused by callee.
note

If the first digit of status code is 4 or 5, the response will be considered as an error response.

3.2. Response body#

Response body, like request body, it must contain well-known data.
Default value: undefined

3.3. Example#

import { IRS } from '@cellularjs/net';
const badRequestIrs = new IRS(  { status: 400, id: 'abc**********' },  {    err: 'BAD_REQUEST', // human friendly code    errs: [      { src: 'name', err: 'MAX_LENGTH', maxLength: 120 },      { src: 'images[3]', err: 'MIME', mime: ['jpg', 'jpeg', 'gif', 'png' ] },      { src: 'variants[0].price', err: 'REQUIRED' },      { src: 'variants[2].quantity', err: 'NUMBER' },    ],  },);
const accessForbiddenIrs = new IRS(  { status: 403 },  { err: 'ACCESS_FORBIDDEN' },);
const successIrs = new IRS();

4. Well-known data#

A well-known data is a data that can be understood by both caller and callee. In the context of CellularJS, it can be transferable object, array, string, number,...