How do I add an adapter part to ores.http?
Table of Contents
The gateway serves each domain through one adapter part named after the domain. The parts are described in ores.http, and ores.http.synthetic is the part to copy: it is the smallest one and it was written from this list.
1. Question
How do I stand up a new per-domain adapter part in ores.http, so its
models can be served by the new server?
2. Answer
Work in this order. The composite root must not name the part before the
part's own CMakeLists.txt files exist, or configure stops with "does not
contain a CMakeLists.txt file".
- Add the part's model,
projects/ores.http/<comp>/modeling/component_overview.org, copied from an existing adapter part with#+component_kind: adapter,#+name:,#+full_name:,#+brief:, and the two#+begin_src cmakeblocks (extra_dependencies,extra_test_dependencies) namingores.<comp>.api.lib. - Copy the four CMake files from the same part — root,
src,tests,modeling— and swap the name throughout. Codegen writes only the twocomponent_files.cmakelists for an adapter, so these four are hand-authored and a regeneration never writes over them. - Add the part to
#+parts:and to the Sub-components table ofprojects/ores.http/modeling/component_overview.org, then regenerate the composite root:compass codegen generate --model projects/ores.http/modeling/component_overview.org --address ores.cmake.component - Generate the umbrella header:
compass codegen generate --model projects/ores.http/<comp>/modeling/component_overview.org --address ores.cppThen copytests/main.cppandtests/test_suite.hppfrom the same part and swap the name. - Write the aggregate by hand —
src/routes/<comp>/<comp>_routes.cppand its header. It is the one file in the part that lists the units, andcheck_route_unitsfails when an opted-in model's unit is missing from it. - Generate the file lists:
projects/ores.codegen/scripts/regenerate_cmake_component_files.py --component ores.http.<comp> - Draw the diagram:
build/scripts/generate_component_puml.py --project ores.http.<comp>then add the three relations after the manual sentinel and render withplantuml -tpngin themodelingdirectory.component-docsfails without the PNG. - Register the part in the server: add
ores.http.<comp>.libto theextra_dependenciesblock ofprojects/ores.http/server/modeling/component_overview.org, regenerate with--address ores.cmake.service, then include the aggregate's header and callregister_routesinprojects/ores.http/server/src/app/application.cpp. - Serve the first collection: add
:ores.cpp.http-route.enabled: trueand#+http_area:to the model's drawer, thencompass codegen generate --model <model> --address ores.cpp.http-routeand--address ores.doc.http-recipe. Add the unit to the aggregate, regenerate the file lists, thenpython3 build/scripts/route_inventory.py --writeandprojects/ores.codegen/scripts/regenerate_http_recipe_inventory.py.
The area in #+http_area: must be one build/scripts/route_classification.py
publishes, and the classification needs a rule for the /api/v1/<area>/
family or the inventory check reports every generated route as unclassified.
3. Tested by
Written while standing up ores.http.synthetic, and followed in that order.
The part and its first collection are in that task's PR; the build, the
component tests and the local gate are the proof.
4. See also
- ores.http.synthetic – the part this recipe was written from.
- ores.http – the composite that holds the parts.