docs: simplify middleware-based sequence

docs/site/Advanced-sequence-topics.md

@@ -0,0 +1,320 @@
+---
+lang: en
+title: 'Advanced Sequence Topics'
+keywords: LoopBack 4.0, LoopBack 4, Node.js, TypeScript, OpenAPI, Sequence
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/Advanced-sequence-topics.html
+---
+
+## Customizing Sequence Actions
+
+There might be scenarios where the default sequence _ordering_ is not something
+you want to change, but rather the individual actions that the sequence will
+execute.
+
+To do this, you'll need to override one or more of the sequence action bindings
+used by the `RestServer`, under the `RestBindings.SequenceActions` constants.
+
+As an example, we'll implement a custom sequence action to replace the default
+"send" action. This action is responsible for returning the response from a
+controller to the client making the request.
+
+To do this, we'll register a custom send action by binding a
+[Provider](https://loopback.io/doc/en/lb4/apidocs.context.provider.html) to the
+`RestBindings.SequenceActions.SEND` key.
+
+First, let's create our `CustomSendProvider` class, which will provide the send
+function upon injection.
+
+{% include code-caption.html content="/src/providers/custom-send.provider.ts" %}
+
+```ts
+import {Send, Response} from '@loopback/rest';
+import {Provider, BoundValue, inject} from '@loopback/core';
+import {writeResultToResponse, RestBindings, Request} from '@loopback/rest';
+
+// Note: This is an example class; we do not provide this for you.
+import {Formatter} from '../utils';
+
+export class CustomSendProvider implements Provider<Send> {
+  // In this example, the injection key for formatter is simple
+  constructor(
+    @inject('utils.formatter') public formatter: Formatter,
+    @inject(RestBindings.Http.REQUEST) public request: Request,
+  ) {}
+
+  value() {
+    // Use the lambda syntax to preserve the "this" scope for future calls!
+    return (response: Response, result: OperationRetval) => {
+      this.action(response, result);
+    };
+  }
+  /**
+   * Use the mimeType given in the request's Accept header to convert
+   * the response object!
+   * @param response - The response object used to reply to the  client.
+   * @param result - The result of the operation carried out by the controller's
+   * handling function.
+   */
+  action(response: Response, result: OperationRetval) {
+    if (result) {
+      // Currently, the headers interface doesn't allow arbitrary string keys!
+      const headers = (this.request.headers as Record<string, string>) || {};
+      const header = headers.accept || 'application/json';
+      const formattedResult = this.formatter.convertToMimeType(result, header);
+      response.setHeader('Content-Type', header);
+      response.end(formattedResult);
+    } else {
+      response.end();
+    }
+  }
+}
+```
+
+Our custom provider will automatically read the `Accept` header from the request
+context, and then transform the result object so that it matches the specified
+MIME type.
+
+Next, in our application class, we'll inject this provider on the
+`RestBindings.SequenceActions.SEND` key.
+
+{% include code-caption.html content="/src/application.ts" %}
+
+```ts
+import {RestApplication, RestBindings} from '@loopback/rest';
+import {
+  RepositoryMixin,
+  Class,
+  Repository,
+  juggler,
+} from '@loopback/repository';
+import {CustomSendProvider} from './providers/custom-send.provider';
+import {Formatter} from './utils';
+import {BindingScope} from '@loopback/core';
+
+export class YourApp extends RepositoryMixin(RestApplication) {
+  constructor() {
+    super();
+    // Assume your controller setup and other items are in here as well.
+    this.bind('utils.formatter')
+      .toClass(Formatter)
+      .inScope(BindingScope.SINGLETON);
+    this.bind(RestBindings.SequenceActions.SEND).toProvider(CustomSendProvider);
+  }
+}
+```
+
+As a result, whenever the SEND action of the
+[`DefaultSequence`](https://loopback.io/doc/en/lb4/apidocs.rest.defaultsequence.html)
+is called, it will make use of your function instead! You can use this approach
+to override any of the actions listed under the `RestBindings.SequenceActions`
+namespace.
+
+## Query string parameters and path parameters
+
+OAI 3.0.x describes the data from a request’s header, query and path in an
+operation specification’s parameters property. In a Controller method, such an
+argument is typically decorated by `@param()`. We've made multiple shortcuts
+available to the `@param()` decorator in the form of
+`@param.<http_source>.<OAI_primitive_type>`. Using this notation, path
+parameters can be described as `@param.path.string`. Here is an example of a
+controller method which retrieves a Note model instance by obtaining the `id`
+from the path object.
+
+```ts
+@get('/notes/{id}', {
+  responses: {
+    '200': {
+      description: 'Note model instance',
+      content: {
+        'application/json': {
+          schema: getModelSchemaRef(Note, {includeRelations: true}),
+        },
+      },
+    },
+  },
+})
+async findById(
+  @param.path.string('id') id: string,
+  @param.filter(Note, {exclude: 'where'}) filter?: FilterExcludingWhere<Note>
+): Promise<Note> {
+  return this.noteRepository.findById(id, filter);
+}
+```
+
+(Notice: the filter for `findById()` method only supports the `include` clause
+for now.)
+
+You can also specify a parameter which is an object value encoded as a JSON
+string or in multiple nested keys. For a JSON string, a sample value would be
+`location={"lang": 23.414, "lat": -98.1515}`. For the same `location` object, it
+can also be represented as `location[lang]=23.414&location[lat]=-98.1515`. Here
+is the equivalent usage for `@param.query.object()` decorator. It takes in the
+name of the parameter and an optional schema or reference object for it.
+
+```ts
+@param.query.object('location', {
+  type: 'object',
+  properties: {lat: {type: 'number', format: 'float'}, long: {type: 'number', format: 'float'}},
+})
+```
+
+The parameters are retrieved as the result of `parseParams` Sequence action.
+Please note that deeply nested properties are not officially supported by OAS
+yet and is tracked by
+[OAI/OpenAPI-Specification#1706](https://github.com/OAI/OpenAPI-Specification/issues/1706).
+Therefore, our REST API Explorer does not allow users to provide values for such
+parameters and unfortunately has no visible indication of that. This problem is
+tracked and discussed in
+[swagger-api/swagger-js#1385](https://github.com/swagger-api/swagger-js/issues/1385).
+
+## Parsing Requests
+
+Parsing and validating arguments from the request url, headers, and body. See
+page [Parsing requests](Parsing-requests.md).
+
+## Invoking controller methods
+
+The `invoke` sequence action simply takes the parsed request parameters from the
+`parseParams` action along with non-decorated arguments, calls the corresponding
+controller method or route handler method, and returns the value from it. The
+default implementation of
+[invoke](https://github.com/strongloop/loopback-next/blob/master/packages/rest/src/providers/invoke-method.provider.ts)
+action calls the handler function for the route with the request specific
+context and the arguments for the function. It is important to note that
+controller methods use `invokeMethod` from `@loopback/core` and can be used with
+global and custom interceptors. See
+[Interceptor docs](Interceptor.md#use-invokemethod-to-apply-interceptors) for
+more details. The request flow for two route flavours is explained below.
+
+For controller methods:
+
+- A controller instance is instantiated from the context. As part of the
+  instantiation, constructor and property dependencies are injected. The
+  appropriate controller method is invoked via the chain of interceptors.
+- Arguments decorated with `@param` are resolved using data parsed from the
+  request. Arguments decorated with `@inject` are resolved from the context.
+  Arguments with no decorators are set to undefined, which is replaced by the
+  argument default value if it's provided.
+
+For route handlers, the handler function is invoked via the chain of
+interceptors. The array of method arguments is constructed using OpenAPI spec
+provided at handler registration time (either via `.api()` for full schema or
+`.route()` for individual route registration).
+
+## Writing the response
+
+The
+[send](https://github.com/strongloop/loopback-next/blob/master/packages/rest/src/providers/send.provider.ts)
+sequence action is responsible for writing the result of the `invoke` action to
+the HTTP response object. The default sequence calls send with (transformed)
+data. Under the hood, send performs all steps required to send back the
+response, from content-negotiation to serialization of the response body. In
+Express, the handler is responsible for setting response status code, headers
+and writing the response body. In LoopBack, controller methods and route
+handlers return data describing the response and it's the responsibility of the
+Sequence to send that data back to the client. This design makes it easier to
+transform the response before it is sent.
+
+LoopBack 4 does not yet provide first-class support for streaming responses, see
+[Issue#2230](https://github.com/strongloop/loopback-next/issues/2230). As a
+short-term workaround, controller methods are allowed to send the response
+directly, effectively bypassing send action. The default implementation of send
+is prepared to handle this case
+[here](https://github.com/strongloop/loopback-next/blob/master/packages/rest/src/writer.ts#L22-L26).
+
+## Handling errors
+
+There are many reasons why the application may not be able to handle an incoming
+request:
+
+- The requested endpoint (method + URL path) was not found.
+- Parameters provided by the client were not valid.
+- A backend database or a service cannot be reached.
+- The response object cannot be converted to JSON because of cyclic
+  dependencies.
+- A programmer made a mistake and a `TypeError` is thrown by the runtime.
+- And so on.
+
+In the Sequence implementation described above, all errors are handled by a
+single `catch` block at the end of the sequence, using the Sequence Action
+called `reject`.
+
+The default implementation of `reject` does the following steps:
+
+- Call
+  [strong-error-handler](https://github.com/strongloop/strong-error-handler) to
+  send back an HTTP response describing the error.
+- Log the error to `stderr` if the status code was 5xx (an internal server
+  error, not a bad request).
+
+To prevent the application from leaking sensitive information like filesystem
+paths and server addresses, the error handler is configured to hide error
+details.
+
+- For 5xx errors, the output contains only the status code and the status name
+  from the HTTP specification. For example:
+
+  ```json
+  {
+    "error": {
+      "statusCode": 500,
+      "message": "Internal Server Error"
+    }
+  }
+  ```
+
+- For 4xx errors, the output contains the full error message (`error.message`)
+  and the contents of the `details` property (`error.details`) that
+  `ValidationError` typically uses to provide machine-readable details about
+  validation problems. It also includes `error.code` to allow a machine-readable
+  error code to be passed through which could be used, for example, for
+  translation.
+
+  ```json
+  {
+    "error": {
+      "statusCode": 422,
+      "name": "Unprocessable Entity",
+      "message": "Missing required fields",
+      "code": "MISSING_REQUIRED_FIELDS"
+    }
+  }
+  ```
+
+During development and testing, it may be useful to see all error details in the
+HTTP response returned by the server. This behavior can be enabled by enabling
+the `debug` flag in error-handler configuration as shown in the code example
+below. See strong-error-handler
+[docs](https://github.com/strongloop/strong-error-handler#options) for a list of
+all available options.
+
+```ts
+app.bind(RestBindings.ERROR_WRITER_OPTIONS).to({debug: true});
+```
+
+An example error message when the debug mode is enabled:
+
+```json
+{
+  "error": {
+    "statusCode": 500,
+    "name": "Error",
+    "message": "ENOENT: no such file or directory, open '/etc/passwords'",
+    "errno": -2,
+    "syscall": "open",
+    "code": "ENOENT",
+    "path": "/etc/passwords",
+    "stack": "Error: a test error message\n    at Object.openSync (fs.js:434:3)\n    at Object.readFileSync (fs.js:339:35)"
+  }
+}
+```
+
+## Keeping your Sequences
+
+For most use cases, the
+[default](https://github.com/strongloop/loopback-next/blob/master/packages/rest/src/sequence.ts)
+sequence supplied with LoopBack 4 applications is good enough for
+request-response handling pipeline. Check out
+[Custom Sequences](#custom-sequences) on how to extend it and implement custom
+actions.