docs: Improve examples of Interceptors with more implementation details

[emonddr]

In https://loopback.io/doc/en/lb4/Interceptors.html#example-interceptors
there are different examples of interceptors.

To understand the example implementations of these interceptors, let's
also show an example implementation of what they are intercepting.

For example:

/**
 * A binding provider class to produce an interceptor that validates the
 * `name` argument
 */
class NameValidator implements Provider<Interceptor> {
  constructor(@inject('valid-names') private validNames: string[]) {}

  value() {
    return this.intercept.bind(this);
  }

  // (doc improvement)
  // This interceptor works as an authorizer for certain endpoints,
  // which takes in the first argument as the name.
  async intercept<T>(
    invocationCtx: InvocationContext,
    next: () => ValueOrPromise<T>,
  ) {
    const name = invocationCtx.args[0];
    if (!this.validNames.includes(name)) {
      throw new Error(
        `Name '${name}' is not on the list of '${this.validNames}`,
      );
    }
    return next();
  }
}

It is not clear what this interceptor is attached to. Is it a function, a class, a request?

How do we know that the name we need to validate is in args[0] of the invocation context?

Providing more implementation details would shed some light on how to use them.

See Reporting Issues for more tips on writing good issues

Acceptane Criteria

• Refine the docs to include more details described above.
• For the example snippet, it implies we need to add more details to InvocationContext's properties, like args, see https://loopback.io/doc/en/lb4/apidocs.context.invocationcontext.html#properties

[dhmlau]

For implementation details, I had 2 blog posts which I'd really like to incorporate some of the content back to the docs, but didn't have the chance:
https://strongloop.com/strongblog/loopback4-interceptors-part1/
https://strongloop.com/strongblog/loopback4-interceptors-part2/

[emonddr]

For implementation details, I had 2 blog posts which I'd really like to incorporate some of the content back to the docs, but didn't have the chance:
https://strongloop.com/strongblog/loopback4-interceptors-part1/
https://strongloop.com/strongblog/loopback4-interceptors-part2/

That would be good, to bring in examples from this blog.

There still needs to be an explanation for how args is being populated with values and what
users should expect to find in it....without having to use a debugger to find out.

if (invocationCtx.methodName == 'create')
         Object.assign(order, invocationCtx.args[0]);
     else if (invocationCtx.methodName == 'updateById')
         Object.assign(order, invocationCtx.args[1]);

Can we perhaps have a argsMap available on the invocation context with key/value pairs so user can
have an understanding of what is available?

[coderade]

The examples are ok for me (when creating interceptor as functions), but I did not understand how to create Interceptor classes with multiple functions and inject services. Is it possible?

For example:

@bind({scope: BindingScope.TRANSIENT})
export class TestingInterceptor implements Provider<Interceptor> {
constructor(@service(ConfigService) public configService: ConfigService) {
}

value() {
    return this.validateFirst.bind(this);
}

validateFirst: Interceptor = async (invocationCtx, next) => {

    const reservation: Reservation = new Reservation();
    reservation.id = '';
    if (invocationCtx.methodName === 'create') {
    Object.assign(reservation, invocationCtx.args[0]);
    }

    if (!reservation.token) {
        throw new HttpErrors['422']('ERROR');
    }

    return next();
};

validateSecond: Interceptor = async (invocationCtx, next) => {

    const reservation: Reservation = new Reservation();
    reservation.id = '';
    if (invocationCtx.methodName === 'validate') {
    Object.assign(reservation, invocationCtx.args[0]);
    }

    const config = config.getValue('TEST');

    if (!reservation.value !== config) {
       throw new HttpErrors['422']('ERROR');
    }


    return next();
};

}

If possible, how can I inject this interceptor in my controller?

Also, I was able to make only the interceptors work only on my controller rest methods, on my services the interceptor is not being called, There is something that I am doing wrong?

[bajtos]

@raymondfeng can you please chime in and help answer @coderade's question posted above?