Class HandlerContext

Class Documentation

class HandlerContext

Shared context for all HTTP handlers.

Provides access to gateway node, configuration, and common utilities that handlers need to process requests.

Public Functions

inline HandlerContext(GatewayNode *node, const CorsConfig &cors_config, const AuthConfig &auth_config, const TlsConfig &tls_config, AuthManager *auth_manager, BulkDataStore *bulk_data_store = nullptr)
inline GatewayNode *node() const

Get gateway node.

inline const CorsConfig &cors_config() const

Get CORS configuration.

inline const AuthConfig &auth_config() const

Get authentication configuration.

inline const TlsConfig &tls_config() const

Get TLS configuration.

inline AuthManager *auth_manager() const

Get authentication manager (may be nullptr if auth disabled)

inline BulkDataStore *bulk_data_store() const

Get bulk data store (may be nullptr if not configured)

inline void set_aggregation_manager(AggregationManager *mgr)

Set the aggregation manager (non-owning, null when aggregation disabled)

inline AggregationManager *aggregation_manager() const

Get the aggregation manager (may be nullptr if aggregation disabled)

tl::expected<void, std::string> validate_entity_id(const std::string &entity_id) const

Validate entity ID (component_id, area_id, etc.)

Parameters:

entity_id – The ID to validate

Returns:

Empty if valid, error message otherwise

tl::expected<std::string, std::string> get_component_namespace_path(const std::string &component_id) const

Get namespace path for a component.

Deprecated:

Use get_entity_info instead for unified entity handling

Parameters:

component_id – Component ID

Returns:

Namespace path or error message

EntityInfo get_entity_info(const std::string &entity_id, SovdEntityType expected_type = SovdEntityType::UNKNOWN) const

Get information about any entity (Component, App, Area, Function)

If expected_type is specified, searches ONLY in that collection. If expected_type is UNKNOWN (default), searches all types in order: Component, App, Area, Function - returns the first match found.

Parameters:

  • entity_id – Entity ID to look up

  • expected_type – Optional: restrict search to specific entity type

Returns:

EntityInfo with resolved details, or EntityInfo with UNKNOWN type if not found

std::optional<std::string> validate_lock_access(const httplib::Request &req, httplib::Response &res, const EntityInfo &entity, const std::string &collection)

Validate lock access for a mutating operation.

Two-phase check:

  1. If locking disabled (no LockManager), allows access

  2. Extracts X-Client-Id header, checks LockManager::check_access()

  3. On denial: sends HTTP error response (409 lock-broken or invalid-request)

Parameters:

  • req – HTTP request (for X-Client-Id header)

  • res – HTTP response (error sent on denial)

  • entity – Entity being accessed

  • collection – Resource collection being mutated (e.g. “configurations”)

Returns:

std::nullopt if allowed, error message string if denied (error already sent)

ValidateResult validate_entity_for_route(const httplib::Request &req, httplib::Response &res, const std::string &entity_id) const

Validate entity exists and matches expected route type.

Unified validation helper that:

  1. Validates entity ID format

  2. Looks up entity in the expected collection (based on route path)

  3. For remote entities (aggregation), forwards the request to the peer gateway

  4. Sends appropriate error responses on failure:

    • 400 with “invalid-parameter” if ID format is invalid

    • 400 with “invalid-parameter” if entity exists but wrong type for route

    • 404 with “entity-not-found” if entity doesn’t exist

Parameters:

  • req – HTTP request (used to extract expected type from path)

  • res – HTTP response (error responses sent here)

  • entity_id – Entity ID to validate

Returns:

EntityInfo on success. On failure, returns ValidationOutcome indicating whether an error was sent (kErrorSent) or the request was forwarded to a peer (kForwarded). In both failure cases the response is already committed and the handler must return immediately.

void set_cors_headers(httplib::Response &res, const std::string &origin) const

Set CORS headers on response if origin is allowed.

Parameters:

  • res – HTTP response

  • origin – Origin header value

bool is_origin_allowed(const std::string &origin) const

Check if origin is allowed by CORS config.

Parameters:

origin – Origin header value

Returns:

true if allowed

Public Static Functions

static std::optional<std::string> validate_collection_access(const EntityInfo &entity, ResourceCollection collection)

Validate that entity supports a resource collection.

Checks EntityCapabilities based on SOVD spec (Table 8). Returns error if the entity type doesn’t support the collection.

Parameters:

  • entity – Entity information (from get_entity_info)

  • collection – Resource collection to validate

Returns:

std::nullopt if valid, error message if invalid

static void send_error(httplib::Response &res, int status, const std::string &error_code, const std::string &message, const nlohmann::json &parameters = {})

Send JSON error response following SOVD GenericError schema.

Creates a response with the following structure: { “error_code”: “entity-not-found”, “message”: “Entity not found”, “parameters”: { … } // optional }

For vendor-specific errors (x-medkit-*), the response includes: { “error_code”: “vendor-error”, “vendor_code”: “x-medkit-ros2-service-unavailable”, “message”: “…” }

Parameters:

  • res – HTTP response object

  • status – HTTP status code

  • error_code – SOVD error code (use constants from error_codes.hpp)

  • message – Human-readable error message

  • parameters – Optional additional parameters for context

static void send_json(httplib::Response &res, const nlohmann::json &data)

Send JSON success response.

static inline rclcpp::Logger logger()

Get logger for handlers.