feat(cpp-boost-beast-client): variant-first oneOf/anyOf/allOf composition

.gitignore

@@ -314,4 +314,13 @@ samples/client/jetbrains/adyen/checkout71/http/client/Apis/http-client.private.e
 \?/
 
 # AI agent caches
-.junie
+.junie
+
+# openai-cpp-sdk build artifacts (Gate A / B harnesses)
+/generated-oas-client/
+/generated-oas-client-negative/
+openai-cpp-sdk/generated-oas/
+openai-cpp-sdk/generated-oas-negative/
+openai-cpp-sdk/generated-openai/
+openai-cpp-sdk/build-generated/
+openai-cpp-sdk/build-master-verification/

docs/generators/cpp-boost-beast-client.md

@@ -32,8 +32,12 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |int32_t|#include <cstdint>|
 |int64_t|#include <cstdint>|
 |std::map|#include <map>|
+|std::monostate|#include <variant>|
 |std::nullptr_t|#include <cstddef>|
+|std::optional|#include <optional>|
+|std::shared_ptr|#include <memory>|
 |std::string|#include <string>|
+|std::variant|#include <variant>|
 |std::vector|#include <vector>|
 
 
@@ -239,11 +243,11 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 | ---- | --------- | ---------- |
 |Simple|✓|OAS2,OAS3
 |Composite|✓|OAS2,OAS3
-|Polymorphism|✗|OAS2,OAS3
-|Union|✗|OAS3
-|allOf|✗|OAS2,OAS3
-|anyOf|✗|OAS3
-|oneOf|✗|OAS3
+|Polymorphism|✓|OAS2,OAS3
+|Union|✓|OAS3
+|allOf|✓|OAS2,OAS3
+|anyOf|✓|OAS3
+|oneOf|✓|OAS3
 |not|✗|OAS3
 
 ### Security Feature

modules/openapi-generator/src/main/resources/cpp-boost-beast-client/CMakeLists.txt.mustache

@@ -49,7 +49,7 @@ endif ()
 
 add_library(${PROJECT_NAME} SHARED)
 
-set_property(TARGET ${PROJECT_NAME} PROPERTY CXX_STANDARD 11)
+set_property(TARGET ${PROJECT_NAME} PROPERTY CXX_STANDARD 17)
 set_property(TARGET ${PROJECT_NAME} PROPERTY CXX_STANDARD_REQUIRED ON)
 set_property(TARGET ${PROJECT_NAME} PROPERTY CXX_EXTENSIONS OFF)
 

modules/openapi-generator/src/main/resources/cpp-boost-beast-client/README.mustache

@@ -0,0 +1,235 @@
+# {{packageName}}
+
+{{#appDescriptionWithNewLines}}{{{.}}}{{/appDescriptionWithNewLines}}
+
+Generated by [OpenAPI Generator](https://openapi-generator.tech).
+{{#generatorVersion}}Generator version: {{generatorVersion}}{{/generatorVersion}}
+
+- API version: {{appVersion}}
+{{^hideGenerationTimestamp}}- Build date: {{generatedDate}}{{/hideGenerationTimestamp}}
+- API namespace: `{{{apiPackage}}}`
+- Model namespace: `{{{modelPackage}}}`
+
+---
+
+## Architecture
+
+This client uses **variant-first composed-schema lowering** — a deliberate departure
+from the default OpenAPI Generator composed-schema handling.
+
+### Breaking model strategy
+
+The generator treats composed schemas (`oneOf`, `anyOf`, `allOf`) as first-class
+C++ types rather than empty object shells. This is a **breaking change**: generated
+model headers, source, and API surfaces are fundamentally different from the previous
+output.
+
+**The break is intentional and acceptable.** No known downstream project depends on
+the prior composed-model output for `cpp-boost-beast-client`. The generator stability
+label stays STABLE because the generated output targets a specific C++ client; the
+prior output for composed schemas was non-functional (empty structs that could not
+hold union data).
+
+| Before | After |
+|--------|-------|
+| Empty struct `AnyOfStringArray {}` | `std::variant<std::string, std::vector<ItemStruct>>` |
+| Composed → `{}` on wire | Correct encode/decode via `toJsonValue`/`fromJsonValue` |
+| Polymorphism disabled | `oneOf`/`anyOf`/`allOf` fully supported |
+
+### Ordered composition lowering
+
+The generator applies the following rules in order to every composed schema:
+
+1. **Merge compatible `allOf` object composition** through generated inheritance and property aggregation. Conflict → error.
+2. **Lower `anyOf`/`oneOf` null unions** with a single non-null branch to `std::optional<T>` (and OAS 3.0 `nullable`).
+3. **Collapse `anyOf` of only string and string-enums to `std::string`.**  
+   Does **not** apply this collapse to `oneOf` unless exclusivity is proven.
+4. **Collapse single remaining non-null branch** to that branch type.
+5. **Deduplicate identical C++ branch types** inside variants.
+6. **Else emit `std::variant<Branches...>`**.
+7. **If still untyped/open**, emit `boost::json::value`.
+
+### OpenAPI → C++ type mapping
+
+| OpenAPI shape | C++ type |
+|---------------|----------|
+| `string` | `std::string` |
+| `integer`/`int32` | `std::int32_t` |
+| `integer`/`int64` | `std::int64_t` |
+| `number` | `double` |
+| `boolean` | `bool` |
+| `anyOf: [T, null]` / nullable `T` | `std::optional<T>` |
+| `oneOf` / non-null `anyOf` unions | `std::variant<...>` |
+| `allOf` object | Inherited/merged value class |
+| array | `std::vector<T>` |
+| map / `additionalProperties` | `std::map<std::string, T>` |
+| free-form JSON | `boost::json::value` |
+| object struct | Value class |
+| cyclic edge | `std::shared_ptr<T>` |
+| `enum` string | `enum class` + string conversion |
+| Discriminator literal | Fixed on encode when branch schema declares a `const` (OAS 3.1) or single-value `enum`; otherwise not injected |
+
+---
+
+## Nullability: omit vs null policy
+
+### Current scope (Phase 2)
+
+The generated encode logic uses a **two-state model** for optional fields:
+
+| Field kind | Encode behavior |
+|-----------|----------------|
+| Non-required, disengaged optional / isSet=false | **Key omitted** from JSON output |
+| Non-required, engaged optional / isSet=true | Key written with converted value |
+| Required, nullable, `std::nullopt` | Key written as JSON `null` |
+| Required, nullable, has value | Key written with converted value |
+
+For non-required fields, the current implementation omits the key when the
+optional is disengaged. The `JsonValueConverter<std::optional<T>>::toJsonValue`
+helper unwraps the inner value; the outer `has_value()` check at the call site
+prevents unreachable `null` output for absent optionals.
+
+### Deferred: full tri-state
+
+A full **tri-state model** (field absent / field present with JSON null / field
+present with JSON value) is **not yet implemented**.  When the schema allows null,
+the current implementation cannot distinguish "field was sent as JSON null" from
+"field was absent" for non-required properties — both result in the key being
+omitted on encode and `std::nullopt` on decode.
+
+A future phase may add a separate `null_state` flag per nullable field to
+preserve the absent-vs-null distinction on the wire, matching OAS 3.1's
+semantic model where a missing key and a present `null` value are distinct.
+
+---
+
+## Compliance testing
+
+Composition lowering is covered by unit tests and OAS fixture specs under:
+
+```text
+modules/openapi-generator/src/test/resources/3_1/cpp-boost-beast-client/
+modules/openapi-generator/src/test/resources/3_1/cpp-boost-beast-client/oas-compliance/
+```
+
+Run:
+
+```sh
+./mvnw -pl modules/openapi-generator \
+  -Dtest=CppBoostBeastClientCodegenTest,CppBoostBeastClientApiCodegenTest test
+```
+
+---
+
+## Media-type-driven streaming (not `stream` flags)
+
+OpenAPI models streaming via the response `content` map, not via boolean parameters:
+
+```yaml
+responses:
+  '200':
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/Response'
+      text/event-stream:
+        schema:
+          $ref: '#/components/schemas/ResponseStreamEvent'
+```
+
+The generator **discovers** media types and schemas from the `content` map. This
+includes same-status multi-content operations where one media type is
+`text/event-stream` and another is `application/json`.
+
+### Required behavior
+
+1. **Client selection** — The caller chooses representation via the `Accept` header.
+   Non-streaming path sets `Accept: application/json`; streaming path sets
+   `Accept: text/event-stream`.
+2. **SSE decoding** — When `text/event-stream` is selected, the generator emits
+   an event-stream parser that decodes each SSE `data:` line using the
+   schema from the `text/event-stream` media type entry (often a `oneOf` union).
+3. **Transport** — Streaming operations use `HttpClient::executeStream`, which
+   reads the response body incrementally and delivers complete SSE events
+   (WHATWG-framed `data` payloads) via callback as they arrive.
+
+### Explicitly forbidden as core OAS behavior
+
+- Hard-coding parameter name `stream` or operationId patterns from any single API.
+- Assuming event type names (`ResponseStreamEvent`, etc.) in the engine.
+- Treating dual media-type content as vendor-specific.
+
+Parameter properties named `stream` in the OpenAPI document are ordinary schema
+parameters — not OAS keywords. The generator does not special-case them.
+
+### Incremental SSE transport
+
+`HttpClient::executeStream` performs incremental `async_read_some` reads and
+frames Server-Sent Events per the WHATWG specification. Each callback receives
+one complete event's data payload (multi-line `data:` fields joined by LF).
+Generated streaming operations parse each event as it is framed. Incomplete
+events at EOF are discarded.
+
+---
+
+## Non-standard format mappings
+
+The generator documents non-standard format mappings as explicit type-mapping
+entries, not as core OAS vocabulary.
+
+| Format | OAS status | C++ type | Notes |
+|--------|-----------|----------|-------|
+| `unixtime` | **Non-standard** (not in OAS format registry) | `std::int64_t` | Optional generator convenience in `getSchemaType` when `format: unixtime` appears. Not core OAS vocabulary. |
+
+This mapping is a **documented non-standard convenience** for APIs that encode
+Unix-epoch seconds as integers. It does **not** imply that `unixtime` is a
+standard OAS format. Specs that omit `format: unixtime` are unaffected. Any API
+using a different time representation (ISO 8601 strings, millisecond epochs,
+etc.) must define its own schema.
+
+---
+
+## Large breaking PR is acceptable
+
+This work ships as a single, large, explicitly-breaking pull request that:
+
+1. Eliminates the prior empty-shell composed-model output entirely.
+2. Replaces it with `std::variant` / `std::optional` / collapsed types.
+3. Updates every mustache template for models and API operations.
+4. Adds OAS composition fixtures and unit tests for lowering rules.
+5. Adds media-type-driven streaming support.
+
+**No attempt is made to preserve backward compatibility with prior generated
+output.** The prior output was non-functional for composed schemas, and no
+known downstream project depends on it. The breaking change is confined to
+a single generator (`cpp-boost-beast-client`) and does not affect any other
+OpenAPI Generator language target.
+
+Reviewers should evaluate the PR against:
+- **OAS compliance** — do the generated types and encode/decode faithfully
+  represent the OpenAPI specification's composition rules?
+- **Fixture coverage** — does every lowering rule have dedicated unit/fixture
+  coverage with green tests?
+
+---
+
+## Requirements
+
+- C++17 compiler (GCC 7+, Clang 8+, MSVC 2019+)
+- CMake 3.14+
+- Boost 1.75+ (Beast, Asio, JSON)
+- OpenSSL 1.1.0+
+
+## Build
+
+```sh
+mkdir build && cd build
+cmake .. -DCMAKE_BUILD_TYPE=Release
+cmake --build .
+```
+
+## Installation
+
+```sh
+cmake --install .
+```

modules/openapi-generator/src/main/resources/cpp-boost-beast-client/api-header.mustache

@@ -65,18 +65,27 @@ public:
     /// <remarks>
     /// {{notes}}
     /// </remarks>
-    virtual {{#returnType}}{{{.}}}{{/returnType}}{{^returnType}}void{{/returnType}}
+    virtual {{#vendorExtensions.x-codegen-streaming-response}}{{#vendorExtensions.x-codegen-stream-element-type}}std::vector<{{{.}}}>{{/vendorExtensions.x-codegen-stream-element-type}}{{^vendorExtensions.x-codegen-stream-element-type}}{{#returnType}}std::vector<{{{.}}}>{{/returnType}}{{^returnType}}void{{/returnType}}{{/vendorExtensions.x-codegen-stream-element-type}}{{/vendorExtensions.x-codegen-streaming-response}}{{^vendorExtensions.x-codegen-streaming-response}}{{#returnType}}{{{.}}}{{/returnType}}{{^returnType}}void{{/returnType}}{{/vendorExtensions.x-codegen-streaming-response}}
     {{#operationId}}{{{.}}}{{/operationId}}{{^operationId}}{{httpMethod}}_{{vendorExtensions.x-codegen-resource-name}}{{/operationId}}(
         {{#allParams}}const {{#vendorExtensions.x-codegen-is-optional-query-parameter}}boost::optional<{{/vendorExtensions.x-codegen-is-optional-query-parameter}}{{{dataType}}}{{#vendorExtensions.x-codegen-is-optional-query-parameter}}>{{/vendorExtensions.x-codegen-is-optional-query-parameter}}& {{{paramName}}}{{^-last}}, {{/-last}}{{/allParams}});
 
+    {{#vendorExtensions.x-codegen-dual-content}}
+    /// <summary>
+    /// {{summary}} (streaming)
+    /// </summary>
+    virtual std::vector<{{#vendorExtensions.x-codegen-dual-stream-element-type}}{{{.}}}{{/vendorExtensions.x-codegen-dual-stream-element-type}}{{^vendorExtensions.x-codegen-dual-stream-element-type}}{{{vendorExtensions.x-codegen-dual-stream-return-type}}}{{/vendorExtensions.x-codegen-dual-stream-element-type}}>
+    {{#operationId}}{{{.}}}{{/operationId}}Stream(
+        {{#allParams}}const {{#vendorExtensions.x-codegen-is-optional-query-parameter}}boost::optional<{{/vendorExtensions.x-codegen-is-optional-query-parameter}}{{{dataType}}}{{#vendorExtensions.x-codegen-is-optional-query-parameter}}>{{/vendorExtensions.x-codegen-is-optional-query-parameter}}& {{{paramName}}}{{^-last}}, {{/-last}}{{/allParams}});
+
+    {{/vendorExtensions.x-codegen-dual-content}}
     {{#vendorExtensions.x-codegen-other-methods}}
     /// <summary>
     /// {{summary}}
     /// </summary>
     /// <remarks>
     /// {{notes}}
     /// </remarks>
-    virtual {{#returnType}}{{{.}}}{{/returnType}}{{^returnType}}void{{/returnType}}
+    virtual {{#vendorExtensions.x-codegen-streaming-response}}{{#vendorExtensions.x-codegen-stream-element-type}}std::vector<{{{.}}}>{{/vendorExtensions.x-codegen-stream-element-type}}{{^vendorExtensions.x-codegen-stream-element-type}}{{#returnType}}std::vector<{{{.}}}>{{/returnType}}{{^returnType}}void{{/returnType}}{{/vendorExtensions.x-codegen-stream-element-type}}{{/vendorExtensions.x-codegen-streaming-response}}{{^vendorExtensions.x-codegen-streaming-response}}{{#returnType}}{{{.}}}{{/returnType}}{{^returnType}}void{{/returnType}}{{/vendorExtensions.x-codegen-streaming-response}}
     {{#operationId}}{{{.}}}{{/operationId}}{{^operationId}}{{httpMethod}}_{{vendorExtensions.x-codegen-resource-name}}{{/operationId}}(
         {{#allParams}}const {{#vendorExtensions.x-codegen-is-optional-query-parameter}}boost::optional<{{/vendorExtensions.x-codegen-is-optional-query-parameter}}{{{dataType}}}{{#vendorExtensions.x-codegen-is-optional-query-parameter}}>{{/vendorExtensions.x-codegen-is-optional-query-parameter}}& {{{paramName}}}{{^-last}}, {{/-last}}{{/allParams}});
     {{/vendorExtensions.x-codegen-other-methods}}