LoopBack 4 Documentation

The @loopback/socketio module uses socket.io to expose LoopBack controllers as WebSocket-friendly endpoints. It is currently marked as Experimental.

Key Constructs

• SocketIoServer: A server type that listens for incoming WebSocket connections and dispatches messages to controllers subscribed to specific namespaces. Each server is attached to an http/https endpoint.
• SocketIo controller: A controller class decorated with metadata to handle:
  • Namespace mapping
  • Connect/disconnect events
  • Subscribing to/consuming messages
  • Publishing/producing messages
• SocketIo middleware or sequence: Allows intercepting and processing WebSocket messages with common logic.

LoopBack 4 uses relations to connect different models, allowing you to define real-world mappings and access CRUD APIs for related data. Unlike LoopBack 3, LoopBack 4 implements relations through constrained repositories, where the target model repository provides a constrained version of itself as a navigational property on the source repository.

LoopBack 4 also utilizes an inclusion resolver to help query data across different relations. A unique inclusion resolver is created for each relation type.

Supported relation types include:

• HasMany
• BelongsTo
• HasOne
• HasManyThrough
• ReferencesMany

Note: hasMany can alternatively be implemented using referencesMany or embedsMany depending on your database paradigm and trade-offs.

The @loopback/authentication-passport module is an adapter designed to plug existing Passport strategies into the @loopback/authentication@3.x system.

Because the LoopBack AuthenticationStrategy interface uses a different contract than the standard Passport Strategy, this adapter converts Passport strategies so they are compatible with LoopBack's extensible authentication system.

Prerequisite: It is strongly recommended to understand the LoopBack authentication system before using this module.

@loopback/metadata is a utility module designed to help developers implement TypeScript decorators, define and merge metadata, and inspect metadata applied to classes and their members. It provides three core capabilities:

• Reflector: A wrapper around reflect-metadata.
• Decorator factories: A collection of factories for creating class, method, property, and parameter decorators that apply metadata to static or instance members.
• MetadataInspector: High-level APIs for inspecting classes and their members to retrieve metadata applied via decorators.

Validation in a LoopBack application can be implemented at multiple layers depending on the requirement. LoopBack provides out-of-the-box type validation in the REST layer, while other logic requires specific configuration or code.

Common validation targets include:

• Method invocations: Validating input and output parameters.
• Model instance properties: Validating specific property constraints (e.g., ensuring age is not less than 0).
• Model collections: Validating collection-level constraints (e.g., ensuring uniqueness of a field).

LoopBack 4 uses Express for its REST server implementation but does not expose Express's native middleware directly. Instead, it provides a specialized middleware model designed to integrate with LoopBack's core patterns: Inversion of Control, Dependency Injection, and Extension Points.

Middleware in LoopBack 4 is designed to:

• Plug into the Sequence to handle HTTP request/response processing (e.g., logging, monitoring, rate limiting) without manual updates to the Sequence class.
• Leverage Dependency Injection for externalized configuration.
• Support existing Express middleware modules with minimal effort, including factory and configuration patterns.
• Operate at two tiers: as part of the Sequence for all requests/responses, or as interceptors around specific controller method invocations.

The @loopback/testlab package provides several categories of utilities for testing LoopBack 4 applications:

• expect: BDD-style assertions.
• sinon: Support for test spies (recording arguments), stubs (pre-programmed behavior), and mocks (pre-programmed behavior and expectations).
• Supertest Helpers: Tools for creating supertest clients for LoopBack applications.
• HTTP Stubs: Request/response stubs that allow writing tests without requiring a listening HTTP server.
• Validation: Swagger/OpenAPI specification validation.
• Test Sandbox: Environment for isolated testing.

LoopBack 4 provides an extensible and composable core written in TypeScript, designed to help developers build large-scale Node.js applications that are scalable and easy to maintain. This tutorial series covers the fundamental design patterns and core modules required to manage complexity in large projects.

Key topics covered in the series include:

• Context Management: Managing artifacts within the application.
• Dependency Injection: Leveraging DI for decoupled code.
• Extension Points: Using and creating extension points to customize behavior.
• Interception: Implementing interception patterns.
• Lifecycle Observation: Observing and reacting to lifecycle events.
• Configuration: Managing application settings.
• Booting: Using convention-based booting to load components.
• Advanced Recipes: Implementing complex architectural patterns.

LoopBack is an open-source Node.js framework designed for API developers to create microservices from existing services or databases. It acts as an API composition layer, connecting inbound API requests to backend resources like databases, REST APIs, SOAP web services, and gRPC microservices.

Key capabilities include:

• API Composition: Glueing inbound communication (HTTP) with outbound integration (connectors).
• Scaffolding: Quickly creating APIs from existing databases using JSON declarations and Node.js code.
• Extensibility: Using middleware, models, datasources, and connectors to implement business logic.

The AuthenticationComponent provides several key providers that power the authentication lifecycle:

• AuthenticationBindings.METADATA.key: Bound to AuthMetadataProvider, which returns authentication decorator metadata of type AuthenticationMetadata.
• AuthenticationBindings.AUTH_ACTION.key: Bound to AuthenticateActionProvider, which returns an authenticating function of type AuthenticateFn.
• AuthenticationBindings.STRATEGY.key: Bound to AuthenticationStrategyProvider, which resolves and returns an authentication strategy of type AuthenticationStrategy.

To secure your API endpoints, you generally follow these steps:

1. Decorate controller endpoints with the @authenticate(strategyName, options?) decorator.
2. Insert the authentication action into your custom REST sequence.
3. Create and register a custom authentication strategy with a unique name.

LoopBack 4 distinguishes between Authentication (verifying a user/entity's identity) and Authorization (deciding if a user can perform a specific action).

To implement authentication in a standard REST sequence, you typically follow these steps:

1. Register the @loopback/authentication component and a specific extension (like @loopback/authentication-jwt) in your application.
2. Enable the authenticate action in your REST sequence.
3. Decorate your controller endpoints with the @authenticate() decorator.
4. Inject the user profile into your controller methods.

Note: If you are using a middleware-based sequence, you do not need to manually add the authenticate action; authentication is enforced by automatically discovered middleware.

The @loopback/rest package provides the core REST server functionality for LoopBack applications, including:

• A custom routing engine.
• Tools for defining application routes.
• OpenAPI 3.0 specification generation (openapi.json/openapi.yaml) via @loopback/openapi-v3.
• A default sequence implementation to manage the request and response lifecycle.

Note: Starting from version 6.0.0, a middleware-based sequence is used as the default for applications generated via the @loopback/cli (lb4 command).