Guards - kto przechodzi przez bramę

Wartownik przy rogatce liczy wszystkich wchodzących i zapisuje godzinę. Robi to samo dla kupca, posłańca i legionisty - bo na rogatce jeszcze nie wiadomo, dokąd który z nich idzie. Dopiero przy drzwiach skarbca stoi ktoś, kto wie, do której komnaty puka przybysz, i dlatego może powiedzieć „ty nie".

To jest cała różnica między middleware a guardem, i w tej lekcji zamkniemy ją do końca. Zaczniemy od domknięcia sprawy z poprzedniej lekcji: jak middleware w ogóle podpina się do aplikacji.

Rejestracja middleware - trzy elementy

Sama klasa middleware nic nie robi, dopóki nie wskażesz, gdzie ma działać. Robi to moduł, który implementuje interfejs

NestModule

configure

1import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
2
3@Module({
4  controllers: [TributesController],
5})
6export class AppModule implements NestModule {
7  configure(consumer: MiddlewareConsumer) {
8    consumer.apply(LoggerMiddleware).forRoutes('tributes');
9  }
10}

Kolejność zapisu jest zawsze ta sama:

configure(consumer: MiddlewareConsumer) {

consumer.apply(LoggerMiddleware)

.forRoutes('tributes')

}

@Injectable()

NestModule

consumer.apply()

configure()

.forRoutes()

Zwróć uwagę na argument

'tributes'

Czego middleware nie wie

Middleware wykonuje się przed guardem i nie zna trasy docelowej. Nie jest to niedopatrzenie autorów frameworka, tylko konsekwencja momentu: middleware działa na poziomie Express, zanim NestJS rozstrzygnie, który kontroler i która metoda obsłużą żądanie. Dostaje

req

res

next

Dlatego middleware świetnie nadaje się do rzeczy niezależnych od celu: logowania, nagłówków CORS, parsowania ciasteczek. Nie nadaje się do decyzji w rodzaju „ten endpoint wymaga roli administratora", bo w chwili jego działania nie istnieje jeszcze pojęcie „tego endpointu".

CanActivate - interfejs strażnika

Guard to klasa implementująca interfejs

CanActivate

NestMiddleware

NestInterceptor

PipeTransform

1@Injectable()
2export class AuthGuard implements CanActivate {
3  canActivate(context: ExecutionContext): boolean {
4    const request = context.switchToHttp().getRequest();
5    const token = request.headers.authorization;
6
7    return !!token;
8  }
9}

Ciało metody czyta się w czterech krokach, zawsze w tej kolejności:

canActivate(context: ExecutionContext) {

const request = context.switchToHttp().getRequest();

const token = request.headers.authorization;

return !!token;

Ta decyzja to wartość logiczna

true

'allowed'

null

!!token

true

false

false

403 Forbidden

ExecutionContext - to, czego brakowało

Argument

context

ExecutionContext

ConfigService

Dwie metody wystarczą na początek.

context.switchToHttp().getRequest()

context.getHandler()

context.getClass()

I właśnie tego middleware nie ma. Guard, mając w ręku handler, może zapytać: „czego ta konkretna metoda wymaga?".

Podpięcie guarda

Guard podpina się dekoratorem

@UseGuards

1@Controller('treasury')
2@UseGuards(AuthGuard)
3export class TreasuryController {
4  @Get()
5  findAll() {
6    return this.treasuryService.findAll();
7  }
8}

Zapis składa się z trzech części:

@UseGuards(

AuthGuard

)

false

Gdy strażnik ma pilnować całej aplikacji, rejestrujesz go globalnie:

app.useGlobalGuards(new AuthGuard())

main.ts

APP_GUARD

new

Reflector - guard, który czyta wymagania

Skoro guard zna handler, może odczytać wymagania zapisane przy nim. Wymagania dopina się przez

SetMetadata

Reflector

1export const Roles = (...roles: string[]) => SetMetadata('roles', roles);
2
3@Injectable()
4export class RolesGuard implements CanActivate {
5  constructor(private reflector: Reflector) {}
6
7  canActivate(context: ExecutionContext): boolean {
8    const requiredRoles = this.reflector.get<string[]>(
9      'roles',
10      context.getHandler(),
11    );
12
13    if (!requiredRoles) {
14      return true;
15    }
16
17    const request = context.switchToHttp().getRequest();
18
19    return requiredRoles.includes(request.user?.role);
20  }
21}

SetMetadata('roles', roles)

'roles'

this.reflector.get<string[]>('roles', context.getHandler())

true

Jeden guard obsługuje w ten sposób całą aplikację:

@Roles('senator')

@Roles('centurion', 'tribune')

SetMetadata

@Roles

@UseGuards

Podsumowanie

Rogatka liczy wchodzących, strażnik skarbca decyduje, @name:

• middleware rejestrujesz w module implementującym

  NestModule

  :

  configure(consumer: MiddlewareConsumer) {

  →

  consumer.apply(LoggerMiddleware)

  →

  .forRoutes('tributes')

  →

  }

  ,
• middleware wykonuje się przed guardem i nie zna trasy docelowej - działa, zanim NestJS rozstrzygnie, który handler obsłuży żądanie,
• guard implementuje interfejs

  CanActivate

  - nie

  NestMiddleware

  , nie

  NestInterceptor

  , nie

  PipeTransform

  ,

• canActivate()

  zwraca

  true

  , żeby zezwolić na dostęp - nie napis

  'allowed'

  , nie obiekt z rolami, nie

  null

  ;

  false

  daje

  403

  i handler się nie wykonuje,
• kolejność w metodzie:

  canActivate(context: ExecutionContext) {

  →

  const request = context.switchToHttp().getRequest();

  →

  const token = request.headers.authorization;

  →

  return !!token;

  ,

• ExecutionContext

  udostępnia informacje o docelowym kontrolerze i metodzie (handlerze) - nie bazę danych, nie system plików, nie konfigurację serwera,

• context.getHandler()

  zwraca metodę,

  context.getClass()

  - kontroler,

  switchToHttp().getRequest()

  - obiekt żądania,
• podpięcie:

  @UseGuards(

  →

  AuthGuard

  →

  )

  , globalnie przez

  useGlobalGuards

  albo token

  APP_GUARD

  ,

• SetMetadata('roles', roles)

  zapisuje wymagania przy handlerze, a

  Reflector

  je odczytuje:

  this.reflector.get<string[]>('roles', context.getHandler())

  .

W następnej lekcji poznasz interceptory - trzeci mechanizm cyklu, który jako pierwszy dotyka odpowiedzi, a nie tylko żądania. A na razie zapamiętaj różnicę: middleware pyta „co przyszło", guard pyta „dokąd to idzie i czy wolno".