HTTP Router

[rohiievych]

Describe the problem

Impress is a good option for new projects that work over WebSocket RPC communication. But this approach cannot facilitate transferring of those projects, where the whole client-server communication is bound on HTTP REST or REST over HTTP APIs. That's why we need a full-featured HTTP router, which let enterprises perform a soft project transition with existing HTTP APIs. The solution should include a convenient way of using all HTTP features like headers or url params and search (query) params.

Describe the solution

Here is an example of desired HTTP routing declaration:

({
  'GET /categories': api.categories.getAll,
  
  'GET /categories/:categoryId/products/:productId/getInfo': {
    args: {
      categoryId: 'param',
      productId: 'param',
      customHeader: { type: 'header', key: 'x-custom-header' },
      filter: { type: 'query', key: 'filter' },
    },
    method: api.products.getInfo,
  },

  'POST /categories/:categoryId/products/create': {
    args: {
      categoryId: 'param',
      product: 'body',
    },
    method: api.products.createProduct,
  },
});

The object describes HTTP features to be used: a verb (e.g. GET, POST) with route including url params (e.g. :categoryId), args with data extracted from HTTP request and the interface method to be called with those args, which are used for RPC by default.

Implementation details:

1. Url params must be prefixed with ':', in order to designate the parameter and to be able to unambiguously parse it.
2. We need to define some special metaschema types for parsing HTTP requests: param, header, query, body. These parts of request are used for carrying arbitrary user data. As an alias you can write an extended form like customHeader: { type: 'header', key: 'x-custom-header' }.
   2.1. HTTP data source types description:
   param - url param like :categoryId;
   header- HTTP header like host: example.com;
   query - url search param like ?id=123456;
   body - HTTP request body like { user: { name: 'Peter' } } or a stream in case of binary uploading.
3. In case the method can be called without args, we can simply put it as a route value.
4. Validation of data types will already be in the interface method, so it won't be placed here.

Alternatives

Currently we can use RPC over HTTP in Impress, but we cannot extract data from url params or headers. In more advanced case we can implement a custom router, but it requires a lot of code related to parsing of HTTP requests.

Additional context

Additionally, this router can be used for browser page routing, which is also very important feature.