┌──────────────────────┐     HTTP/JSON over UDS      ┌──────────────────────┐
│  Python CLI tools    │  ─────────────────────────►  │   wazuh-engine       │
│  (engine-suite)      │  ◄─────────────────────────  │   (C++ HTTP server)  │
│                      │                               │                      │
│  Uses APIClient      │   Unix socket path            │  httplib server on   │
│  from                │   /run/wazuh-server/analysis   │  UDS, routes to     │
│  api-communication   │                               │  handler functions   │
└──────────────────────┘                               └──────────────────────┘

api/
├── CMakeLists.txt                              # INTERFACE library linking all sub-modules
├── README.md                                   # This document
│
├── adapter/                                    # Core framework (header-only)
│   ├── include/api/adapter/
│   │   ├── adapter.hpp                         # RouteHandler typedef, proto↔HTTP helpers
│   │   └── helpers.hpp                         # tryGetProperty helper
│   └── test/include/api/adapter/
│       └── baseHandler_test.hpp                # GTest base fixture for handler tests
│
├── shared/                                     # Shared constants (header-only)
│   └── include/api/shared/constants.hpp
│
├── router/                                     # Router route management handlers
│   ├── include/api/router/handlers.hpp
│   ├── src/handlers.cpp
│   └── test/src/unit/handlers_test.cpp
│
├── geo/                                        # GeoIP database query handlers
│   ├── include/api/geo/handlers.hpp
│   ├── src/handlers.cpp
│   └── test/src/unit/handlers_test.cpp
│
├── tester/                                     # Tester session & run handlers
│   ├── include/api/tester/handlers.hpp
│   ├── src/handlers.cpp
│   └── test/src/unit/handlers_test.cpp
│
├── event/                                      # Event ingestion handlers + NDJson parser
│   ├── include/api/event/
│   │   ├── handlers.hpp
│   │   └── ndJsonParser.hpp
│   ├── src/handlers.cpp
│   └── test/src/unit/
│
├── archiver/                                   # Archive enable/disable/status handlers
│   ├── include/api/archiver/handlers.hpp
│   ├── src/handlers.cpp
│   └── test/src/unit/handlers_test.cpp
│
├── rawevtindexer/                              # Raw event indexer status
│   ├── include/api/rawevtindexer/handlers.hpp
│   ├── src/handlers.cpp
│   └── test/src/unit/handlers_test.cpp
│
├── cmcrud/                                     # Content Manager: namespace, policy, resource CRUD
│   ├── include/api/cmcrud/handlers.hpp
│   ├── src/handlers.cpp
│   └── test/src/unit/handlers_test.cpp
│
└── ioccrud/                                    # IOC (Indicator of Compromise) sync handlers
    ├── include/api/ioccrud/handlers.hpp
    ├── src/handlersSync.cpp
    └── test/src/unit/handlers_test.cpp

using RouteHandler = std::function<void(const httplib::Request&, httplib::Response&)>;

// In namespace api::<module>::handlers
adapter::RouteHandler activateArchiver(const std::shared_ptr<::archiver::IArchiver>& archiver);

inline void registerHandlers(const std::shared_ptr<::archiver::IArchiver>& archiver,
                             const std::shared_ptr<httpsrv::Server>& server)
{
    server->addRoute(httpsrv::Method::POST, "/archiver/activate", activateArchiver(archiver));
    server->addRoute(httpsrv::Method::POST, "/archiver/deactivate", deactivateArchiver(archiver));
    server->addRoute(httpsrv::Method::POST, "/archiver/status", getArchiverStatus(archiver));
}

adapter::RouteHandler activateArchiver(const std::shared_ptr<::archiver::IArchiver>& archiver)
{
    return [weakArchiver = std::weak_ptr(archiver)](const auto& req, auto& res)
    {
        using RequestType = eArchiver::ArchiverActivate_Request;
        using ResponseType = eEngine::GenericStatus_Response;

        // 1. Lock the weak_ptr and parse the protobuf request in one call
        auto result = adapter::getReqAndHandler<RequestType, ResponseType, ::archiver::IArchiver>(
            req, weakArchiver);
        if (adapter::isError(result)) {
            res = adapter::getErrorResp(result);
            return;
        }

        // 2. Destructure the result
        auto [archiver, protoReq] = adapter::getRes(result);

        // 3. Execute domain logic via the interface
        archiver->activate();

        // 4. Build and return the protobuf response
        ResponseType eResponse;
        eResponse.set_status(eEngine::ReturnStatus::OK);
        res = adapter::userResponse(eResponse);
    };
}

# Example: archiver CMakeLists.txt
add_library(api_archiver STATIC ${SRC_DIR}/handlers.cpp)
target_link_libraries(api_archiver PUBLIC api::adapter archiver::iface)
add_library(api::archiver ALIAS api_archiver)

{Action}{Resource}_{Request|Response}

cd src/engine
cmake --preset debug -DENGINE_GENERATE_PROTO=ON
cmake --build ./build --target generate_protobuf_code

/usr/bin/make --directory ./src TARGET=server  # with ENGINE_GENERATE_PROTO=ON in CMake

pip install -e src/engine/tools/api-communication

from api_communication.client import APIClient

client = APIClient("/run/wazuh-server/analysis")  # UDS path

# Option 1: send_recv (returns raw dict)
error, response_dict = client.send_recv(proto_request_message)

# Option 2: send (validates response against a proto type)
error, response_dict = client.send(request_proto, response_proto)

# Option 3: jsend (send raw JSON, use proto only for endpoint routing)
error, response_dict = client.jsend(json_dict, request_proto, response_proto)

def get_endpoint(message: Message) -> Tuple[Optional[str], str, str]:
    """Returns (error, endpoint_path, http_method)"""
    if isinstance(message, archiver.ArchiverActivate_Request):
        endpoint = 'archiver/activate'
    # ... instanceof checks for all message types

pip install -e src/engine/tools/engine-suite

# File: engine_archiver/cmds/activate.py

from api_communication.client import APIClient
import api_communication.proto.archiver_pb2 as archiver
import api_communication.proto.engine_pb2 as engine

def run(args):
    client = APIClient(args['api_socket'])

    request = archiver.ArchiverActivate_Request()
    error, response = client.send_recv(request)
    if error:
        sys.exit(f'Error: {error}')

    parsed = ParseDict(response, engine.GenericStatus_Response())
    if parsed.status == engine.ERROR:
        sys.exit(f'Error: {parsed.error}')

    return 0

def configure(subparsers):
    parser = subparsers.add_parser('activate', help='Activate the archiver')
    parser.set_defaults(func=run)

def parse_args():
    parser = argparse.ArgumentParser(prog='engine-archiver')
    parser.add_argument('--api-socket', type=str, default=Constants.SOCKET_PATH)
    subparsers = parser.add_subparsers(title='subcommands', required=True, dest='subcommand')

    configure_activate(subparsers)
    configure_deactivate(subparsers)
    configure_status(subparsers)

    return parser.parse_args()

def main():
    args = parse_args()
    args.func(vars(args))

// src/engine/source/proto/src/example.proto
syntax = "proto3";
import "engine.proto";
package com.wazuh.api.engine.example;

message ExampleAction_Request {
    string name = 1;
    optional string description = 2;
}

message ExampleAction_Response {
    ReturnStatus status = 1;
    optional string error = 2;
    string result = 3;
}

cd src/engine
cmake --preset debug -DENGINE_GENERATE_PROTO=ON
cmake --build ./build --target generate_protobuf_code

#ifndef API_EXAMPLE_HANDLERS_HPP
#define API_EXAMPLE_HANDLERS_HPP

#include <api/adapter/adapter.hpp>
#include <example/iexample.hpp>  // Your domain interface
#include <base/baseTypes.hpp>

namespace api::example::handlers
{

adapter::RouteHandler exampleAction(const std::shared_ptr<::example::IExample>& example);

inline void registerHandlers(const std::shared_ptr<::example::IExample>& example,
                             const std::shared_ptr<httpsrv::Server>& server)
{
    server->addRoute(httpsrv::Method::POST, "/example/action", exampleAction(example));
}

} // namespace api::example::handlers

#endif // API_EXAMPLE_HANDLERS_HPP

#include <api/example/handlers.hpp>
#include <base/logging.hpp>
#include <eMessages/example.pb.h>

namespace api::example::handlers
{
namespace eExample = adapter::eEngine::example;
namespace eEngine = adapter::eEngine;

adapter::RouteHandler exampleAction(const std::shared_ptr<::example::IExample>& example)
{
    return [lambdaName = logging::getLambdaName(__FUNCTION__, "apiHandler"),
            weakExample = std::weak_ptr(example)](const auto& req, auto& res)
    {
        using RequestType = eExample::ExampleAction_Request;
        using ResponseType = eExample::ExampleAction_Response;

        auto result = adapter::getReqAndHandler<RequestType, ResponseType, ::example::IExample>(
            req, weakExample);
        if (adapter::isError(result)) {
            res = adapter::getErrorResp(result);
            return;
        }

        auto [handler, protoReq] = adapter::getRes(result);

        // Execute domain logic
        const auto actionResult = handler->doAction(protoReq.name());

        // Build and return response
        ResponseType eResponse;
        eResponse.set_status(eEngine::ReturnStatus::OK);
        eResponse.set_result(actionResult);
        res = adapter::userResponse(eResponse);
    };
}
} // namespace api::example::handlers

set(SRC_DIR ${CMAKE_CURRENT_LIST_DIR}/src)
set(INC_DIR ${CMAKE_CURRENT_LIST_DIR}/include)

add_library(api_example STATIC ${SRC_DIR}/handlers.cpp)
target_include_directories(api_example PUBLIC ${INC_DIR} PRIVATE ${SRC_DIR})
target_link_libraries(api_example PUBLIC api::adapter example::iface)
add_library(api::example ALIAS api_example)

if(ENGINE_BUILD_TEST)
    set(TEST_SRC_DIR ${CMAKE_CURRENT_LIST_DIR}/test/src)
    set(UNIT_SRC_DIR ${TEST_SRC_DIR}/unit)

    add_executable(api_example_utest ${UNIT_SRC_DIR}/handlers_test.cpp)
    target_link_libraries(api_example_utest PRIVATE
        api::example GTest::gtest_main api::adapter::test example::mocks)
    gtest_discover_tests(api_example_utest)
endif()

import api_communication.proto.example_pb2 as example

# Inside get_endpoint():
    # Example
    if isinstance(message, example.ExampleAction_Request):
        endpoint = 'example/action'

import sys
from google.protobuf.json_format import ParseDict

from api_communication.client import APIClient
import api_communication.proto.example_pb2 as example
import api_communication.proto.engine_pb2 as engine


def run(args):

    # Get the params
    api_socket: str = args['api_socket']

    # Create API client
    client = APIClient(api_socket)

    # Create the request
    request = example.ExampleAction_Request()
    request.name = args['name']
    if args['description']:
        request.description = args['description']

    # Send the request
    error, response = client.send_recv(request)
    if error:
        sys.exit(f'Error executing action: {error}')

    # Parse the response
    parsed_response = ParseDict(response, engine.GenericStatus_Response())
    if parsed_response.status == engine.ERROR:
        sys.exit(f'Error executing action: {parsed_response.error}')

    return 0


def configure(subparsers):
    parser = subparsers.add_parser('action', help='Execute an example action')
    parser.add_argument('name', type=str, help='Name of the example')
    parser.add_argument('-d', '--description', type=str, default=None,
                        help='Description of the action (optional)')
    parser.set_defaults(func=run)

import sys
import json
from google.protobuf.json_format import ParseDict
from shared.dumpers import dict_to_str_yml

from api_communication.client import APIClient
import api_communication.proto.example_pb2 as example
import api_communication.proto.engine_pb2 as engine


def run(args):

    # Get the params
    api_socket: str = args['api_socket']

    # Create API client
    client = APIClient(api_socket)

    # Create the request
    request = example.ExampleGet_Request()
    request.name = args['name']

    # Send the request
    error, response = client.send_recv(request)
    if error:
        sys.exit(f'Error getting example: {error}')

    # Parse the response
    parsed_response = ParseDict(response, example.ExampleGet_Response())
    if parsed_response.status == engine.ERROR:
        sys.exit(f'Error getting example: {parsed_response.error}')

    # Print the response in the requested format
    if args['output_format'] == 'json':
        print(json.dumps(response, indent=4))
    else:
        print(dict_to_str_yml(response))

    return 0


def configure(subparsers):
    parser = subparsers.add_parser('get', help='Get example details')
    parser.add_argument('name', type=str, help='Name of the example to get')
    parser.add_argument('-f', '--output-format', type=str,
                        choices=['text', 'json'], default='text',
                        help='Output format (text or json). Default: text')
    parser.set_defaults(func=run)

import sys

from api_communication.client import APIClient
import api_communication.proto.engine_pb2 as engine
import api_communication.proto.example_pb2 as example


def run(args):

    # Get the params
    api_socket: str = args['api_socket']

    # Create the request
    request = example.ExampleUpsert_Request()
    request.name = args['name']

    content = args['content']
    # Read all content from stdin if not provided as argument
    if not content:
        content = sys.stdin.read()
    request.ymlContent = content

    # Create the api request
    try:
        client = APIClient(api_socket)
        error, response = client.send(request, engine.GenericStatus_Response())

        if error:
            sys.exit(f'Error upserting example: {error}')

    except Exception as e:
        sys.exit(f'Error upserting example: {e}')

    return 0


def configure(subparsers):
    parser = subparsers.add_parser('upsert', help='Upsert an example resource')
    parser.add_argument('name', type=str, help='Name of the resource to upsert')
    parser.add_argument('-c', '--content', type=str, default='',
                        help='Content of the item, can be passed as argument or '
                        'redirected from a file using the "|" operator or the "<" '
                        'operator.')
    parser.set_defaults(func=run)

from engine_public.cmds.example.action import configure as configure_example_action
from engine_public.cmds.example.get import configure as configure_example_get

# Inside parse_args(), after creating subparsers:
configure_example_action(subparsers)
configure_example_get(subparsers)

from engine_private.cmds.example.action import configure as configure_example_action
from engine_private.cmds.example.get import configure as configure_example_get

# Inside parse_args():
example_parser = subparsers.add_parser('example', help='Example operations')
example_subparsers = example_parser.add_subparsers(
    title='example commands', required=True, dest='example_command')

configure_example_action(example_subparsers)
configure_example_get(example_subparsers)

paths:
  /example/action:
    post:
      tags:
        - Example
      summary: Execute an example action
      description: Executes the example action with the given parameters.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExampleAction_Request"
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExampleAction_Response"
        "400":
          $ref: "#/components/responses/BadRequest_400"
        "500":
          $ref: "#/components/responses/InternalServerError_500"

components:
  schemas:
    ExampleAction_Request:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Name parameter
        description:
          type: string
          nullable: true
          description: Optional description

    ExampleAction_Response:
      allOf:
        - $ref: "#/components/schemas/Response"
        - type: object
          properties:
            result:
              type: string
              description: The action result

#include <gtest/gtest.h>
#include <api/adapter/baseHandler_test.hpp>
#include <api/example/handlers.hpp>
#include <example/mockExample.hpp>
#include <eMessages/example.pb.h>

using namespace api::adapter;
using namespace api::test;
using namespace api::example::handlers;
using namespace ::example::mocks;

using ExampleHandlerTest = BaseHandlerTest<::example::IExample, MockExample>;
using ExampleHandlerT = Params<::example::IExample, MockExample>;

TEST_P(ExampleHandlerTest, Handler)
{
    auto [reqGetter, handlerGetter, resGetter, mocker] = GetParam();
    handlerTest(reqGetter, handlerGetter, resGetter, m_iHandler, m_mockHandler, mocker);
}

INSTANTIATE_TEST_SUITE_P(
    Api,
    ExampleHandlerTest,
    ::testing::Values(
        // Success case
        ExampleHandlerT(
            []() {
                eEngine::example::ExampleAction_Request protoReq;
                protoReq.set_name("test");
                return createRequest(protoReq);
            },
            [](const std::shared_ptr<::example::IExample>& h) {
                return exampleAction(h);
            },
            []() {
                eEngine::example::ExampleAction_Response protoRes;
                protoRes.set_status(eEngine::ReturnStatus::OK);
                protoRes.set_result("success");
                return userResponse(protoRes);
            },
            [](auto& mock) {
                EXPECT_CALL(mock, doAction("test")).WillOnce(Return("success"));
            }
        ),
        // Bad request case
        ExampleHandlerT(
            []() {
                httplib::Request req;
                req.body = "not json";
                req.set_header("Content-Type", "text/plain");
                return req;
            },
            [](const std::shared_ptr<::example::IExample>& h) {
                return exampleAction(h);
            },
            []() {
                return userErrorResponse<eEngine::GenericStatus_Response>(
                    "Failed to parse protobuff json request: ...");
            },
            [](auto&) {}
        )
    )
);