feat(qos): add N5 QoS core processing and N7 commit and notify

[tariromukute]

Merge Requests on GitLab

• https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-upf/-/merge_requests/111
• https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-smf/-/merge_requests/328
• https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-amf/-/merge_requests/444
• https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-fed/-/merge_requests/253
• https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-common-build/-/merge_requests/19
• https://gitlab.eurecom.fr/oai/cn5g/oai-cn5g-pcf/-/merge_requests/73

Description

The use case: an Application Function asks the 5G core for better-than-best-effort treatment for one media flow — "4 Mbps down, guaranteed, under 150 ms" — and the network delivers it on a PDU session (an established user data connection) that is already up, without interrupting the user's traffic.

Structurally the PCF is a policy decision service: an HTTP/2 JSON API (N5) over one CRUD resource (an app-session = one AF quality request for one flow), which validates against operator limits and the subscriber's contract, translates into a policy document, attaches it to the right per-user session record, and pushes the result over a second HTTP/2 call (N7) to the SMF, which programs the data plane (UPF).

  ┌────┐   N5 / TS 29.514              ┌─────────────┐   N7 / TS 29.512       ┌─────┐   N4    ┌─────┐
  │ AF │ ────────────────────────────► │     PCF     │ ────────────────────►  │ SMF │ ──────► │ UPF │
  └────┘  POST/GET/PATCH/DELETE        │  (this MR)  │  SmPolicy UpdateNotify └─────┘         └─────┘
   API      /app-sessions              └─────────────┘   (outbound call)      applies       moves the
  client   (our inbound API)                                                 our policy      packets

  [1] BIND       find the live N7 association (per-user session record) for (ueIpv4, supi, dnn)
   │             ──► returns its current decision AND its version
  [2] DERIVE     MediaComponent ──► QosData + PccRule (SDF filters) + QosCharacteristics
   │             = a treatment (bandwidth/priority/latency class) + packet filters match rule.
  [3] AUTHORIZE  allowed 5QI · ARP range · per-flow MBR cap · GBR<=MBR · cumulative non-GBR vs.
   │             subscribed Session-AMBR  (permitted profile? priority in range? floor below
   │             ceiling? do all flows together fit the user's total budget?)
   │             └─ reject ─────────► 403 to AF, nothing committed anywhere
  [4] VALIDATE   referential integrity — no rule may point at a treatment absent from the document
   │             └─ inconsistent ───► 500 — PCF-side fault (code or config), not the AF's
  [5] COMMIT     apply the delta to the association ONLY IF still at [1]'s version
   │             (compare-and-swap: write only if nobody wrote since we read)
   │             └─ version moved ──► re-derive (restart) from [2] against the new base (max 3 tries)
  [6] NOTIFY     full SmPolicyDecision ──► SMF ──► UPF installs / modifies the QoS flow
        ├─ applied ──────────────► 201 (200 on PATCH) to AF; app-session ledger updated
        ├─ temporary / ambiguous ─► bounded retry with backoff. Never a rollback.
        └─ permanent rejection ───► compensating rollback (per-key staleness check), then AF
                                    failure notification (next phase)

Steps [2]-[4] are pure, which is what makes the retry at [5] safe. PATCH and DELETE walk the same six steps: PATCH re-derives the same medCompN (the AF's own media-component key, reused as a stable id) so a repeat request upserts rather than duplicates; DELETE derives a removals-only delta from the session's ledger.

Two properties shaped the design:

• Concurrent AF requests on one PDU session are serialisable — two AFs updating the same user's session at once cannot corrupt each other's result, nor together exceed a limit each satisfied alone. Policy Authorization pushes an incremental SmPolicyDelta (only the keys it touched) applied under an optimistic version-CAS (compare-and-swap), re-deriving against the committed base on conflict (step [5]).
• An SMF rejection never leaves the PCF and SMF disagreeing — the notify response is classified per TS 29.512 Table 5.7.3-2 into retry-eligible vs. confirmed-permanent: bounded retry for the former, staleness-checked compensating rollback for the latter. Deliberately biased so an ambiguous failure (timeout, dropped connection, unmodeled status) never rolls back — undoing a change the SMF did apply is worse than retrying one it didn't.

Legend: ✅ real · 🟡 partial · 🔶 mock · ⬜ deferred to a later MR in this series

Phase 1 — Core QoS Processing ([QOS])

• ✅ Session binding (sm_session_binding) — resolves which established user session an AF request applies to, keyed on UE IP / subscriber id / data-network name.
• ✅ handle_qos_requirements() — templated over MediaComponent (create) and MediaComponentRm (PATCH), the generated create/update variants of one wire object, so there is one implementation rather than two that drift.
• ✅ create_qos_data_from_media_component() — real QosData + PccRule per TS 29.513 §7.3.3: MBR (ceiling) from marBw/summed per-SDF, GBR (floor) from mirBw, 5QI from a latency heuristic, SDF filters from medSubComps — or the operator's preset when qosReference resolves. Deterministic medCompN-keyed ids, so a PATCH modifies in place with precedence reused, not reassigned. resPrio → ARP priorityLevel is not mapped (see Known Issues).
• ✅ create_qos_characteristics() — real entry (priority level, packet delay budget, packet error rate, resource type) for non-standardized 5QIs; a no-op for standardized ones, whose meaning every downstream node already knows.
• ✅ validate_qos_authorization() — dynamic-5QI allow-list, ARP range, per-flow MBR cap, cumulative non-GBR vs. authorized Session-AMBR, GBR≤MBR. The one real policy call: when the network never sent the user's bandwidth budget, allow or deny? Configurable, defaults to allow per the spec's own wording.
• ✅ validate_and_merge_decision() — insert_or_assign so other app-sessions' entries survive, plus referential-integrity checks (no dangling refQosData/refTcData, no duplicate ids, unambiguous precedence).
• ✅ validate_policy_decision() — pre-notification gate on both create and PATCH; a self-inconsistent decision is our bug (500), never sent downstream.
• ✅ QoS modification via PATCH (§1.6) — modify in place, add, or remove via fStatus: REMOVED (including one sub-component of a retained component); all three re-run create's authorization/merge/validation gates.
• ✅ RFC 7396 JSON Merge Patch of the stored ascReqData (merge_patch_context()) — scalars replaced, components and sub-components merged/added/removed, so a GET after a PATCH reflects the change.
• ✅ GET /app-sessions/{id}; POST → 201 + Location + negotiated ascRespData.suppFeat; PATCH → 200 + merged context; Content-Type enforced on every body-carrying endpoint (415 otherwise).
• ✅ Operator QoS policy is config-driven, not hardcoded (see Configuration Updates).
• ✅ App-session model: app_session aggregate root with a qos_context ledger holding identifiers only — the QosData/PccRule payload's single source of truth stays the association's decision, so the two cannot drift. The ledger is written only after a successful commit; derivation targets a scratch object, so a rejected or retried attempt leaves no trace.
• ✅ app_session_storage over a generic injectable crud_store — restart-safe UUID ids, 1:N association_id → app-sessions index. app_session_record fixes the durable schema now so MR 3 is a backend swap at this seam; this MR ships the in-memory backend.
• 🟡 N5 events-subscription endpoints ({PUT,DELETE} /app-sessions/{id}/events-subscription, §4.2.6) still return 404 — held for MR 2, since nothing consumes a subscription until the notification infrastructure exists.

Phase 2 — Cross-Service Coordination ([QOS-SMF])

The PCF's two internal services (Policy Authorization owns the AF-facing API; SM Policy Control owns the session records and the downstream call) communicate over an in-process boost::signals2 event bus rather than calling each other directly.

• ✅ SmPolicyDelta — incremental change set over qosDecs/pccRules/qosChars/traffContDecs, with compute_sm_policy_delta()/apply_sm_policy_delta(). Pushing a delta rather than a whole decision removes the lost-update race on concurrent PATCH: unchanged keys are omitted, so an apply only touches what that request changed. Same reasoning as PATCH rather than PUT on a shared resource.
• ✅ Optimistic (version-CAS) commit — binding returns the decision and its version; handle_commit_decision_request() applies the delta copy-on-write under the association lock only if still at that version, else returns current version + decision for the caller to re-derive (decision_applier::apply, 3 attempts). Closes two races: the ordinary lost update, and the subtler one where two requests each pass a cumulative check against the same stale snapshot — two AFs requesting 60 Mbps each against a 100 Mbps Session-AMBR can no longer both succeed.
• ✅ Commit split from notify — CAS+persist and notify are separate operations; the blocking SMF round-trip runs off-lock on an immutable snapshot [CP.22, the C++ Core Guidelines rule against holding a lock across a blocking call], and the notify re-reads live state. Necessary because the PCF runs several HTTP workers, so another request can commit to the same association between our commit releasing the lock and our notify reacquiring it.
• ✅ send_sm_policy_control_update_notify() — delivers the full decision (pccRules, qosDecs, qosChars), confirmed against a live SMF. Full-not-delta is deliberate, not an oversight: the delta is PCF-internal because the partner SMF diffs the full object itself and a partial SmPolicyDecision on the wire is an interop hazard. Internally incremental, externally complete.
• ✅ classify_smf_notify_response() — maps (HTTP status, body) to applied / permanent_rejection (only PCC_RULE_EVENT, the one cause proving a retry is futile) / temporary_rejection / transport_ambiguous per Table 5.7.3-2. Handles the awkward 200-with-PartialSuccessReport (success status, failure body) and defaults unmodeled statuses to ambiguous. Pure function, so the whole matrix is unit-tested without mocking HTTP.
• ✅ retry_drain_queue — re-attempts temporary/ambiguous notifies off the task_tick heartbeat with exponential backoff, per-entry TTL and a hard cap; each attempt re-fetches live state. Never rolls back. Both bounds present so it cannot grow or retry forever.
• ✅ Compensating rollback — pending_rollback_tracker records what each commit would undo; compute_rollback_delta() reverts a key only if unchanged since that commit (else skipped and logged), which stops a blind revert orphaning a rule a later request depends on; perform_compensating_rollback() always re-reads live state, never the tracker's stale snapshot. The rollback re-commits through the same commit+notify path — one path, no special case to keep in sync.
• ✅ Inline rejection (same attempt) and delayed rejection (sm_policy_update_failed from the drain) converge on one compensate_if_pending(), so there is nothing to race.
• ✅ Recovery bounds config-driven (pcf.notify_failure_recovery); post-commit snapshot persisted to policy storage off-lock; association decision version-bumped copy-on-write.
• 🟡 Cross-service PCC-rule coordination — collision avoidance by construction (id prefix + reserved precedence band, duplicate ids rejected on merge); active conflict detection and an SM-side convention are not built.
• 🔶 notify_af_qos_update_failed() — logs-only stub kept on the rollback path so the call site, arguments and tests are ready for MR 2 to fill in.
• ⬜ Deferred, each with its rationale in Known Issues: resource-management coordination (§2.4), §6.1.3.7 pre-emption-based conflict handling, AF-notification coordination (§2.6, MR 2), decision history, and qosMonDecs (Phase 4, MR 2).

Tested Environment (e.g., radios, interfaces, CN)

Full OAI 5GC under Docker Compose from oai-cn5g-fed (docker-compose-basic-nrf-qos.yaml + docker-compose-ueransim-qos.yaml): NRF, UDR, UDM, AUSF, AMF, SMF (oai-smf:qos-mod), UPF (oai-upf:fix-pfcp-mod), this PCF, UERANSIM gNB + 2 UEs, curl-based AF container.

• Unit tests — 247 GoogleTest cases, 20 suites, all passing. New in this MR, along with the test infrastructure itself (BUILD_TESTING=ON → the pcf_unit_tests target, discovered by CTest). Build via the Docker checks stage if a native build hits the pre-existing missing-<cstdint> issue in the common submodule.
• End-to-end — pa_app_session_tests.py, 19/19 assertions passing against the live stack. New in this MR; walks the full app-session lifecycle (create → read → modify in place / add / remove → delete) plus a deliberately invalid modification that must be rejected without side effects.

Configuration Updates (e.g., files, parameters)

All blocks optional; omitting one keeps documented defaults.

• etc/config.yaml → pcf.local_policy.qos_reference_path (operator QoS presets, e.g. OAI_QOS_GBR_VIDEO_1).
• etc/config.yaml → pcf.qos_authorization: allowed_dynamic_5qi, max_flow_mbr_ul/dl, max_session_ambr_ul/dl, reject_on_missing_subscription. Defaults permissive (no cap / any 5QI / fail-open).
• etc/config.yaml → pcf.notify_failure_recovery: retry_drain_ttl_seconds, retry_drain_max_entries, max_notify_retries, retry_backoff_initial_ms, rollback_tracker_ttl_seconds, rollback_tracker_max_entries. Unprescribed by TS 29.512/29.514, so operator-tunable; defaults 30 s TTLs, 10 000-entry caps, 3 retries, 500 ms backoff doubling.
• New file etc/policies/qos_references/oai_qos_references.yaml. Configured as pcf.local_policy.qos_reference_path
  (default: /openair-pcf/policies/qos_references)
• Build: -DUSE_ODB (default OFF) gates all ODB/MySQL code and linkage.

Known Issues / Limitations

Scheduled — resolved by a later MR in this series

Limitation	Resolved by
AF notification + QoS monitoring absent	MR 2. A subscription has nothing to feed until the notification path exists.
App-session / binding state in-memory only	MR 3. Schema and storage seam are already fixed, so it is a backend swap, not a redesign.
No explicit QoS change-detection step — modification works by idempotent re-derivation, so nothing reports which attributes changed	MR 2, which needs a change summary for its notifications.
Asynchronous, SMF-initiated rule-failure reports are not handled — a separate Npcf_SMPolicyControl_Update carrying ruleReports is accepted and discarded, so an SMF that accepts our notify and only later fails to install the rules leaves the PCF believing the QoS is active, with no rollback and no AF notification. TS 29.512 §4.2.4.15, §4.2.4.7 (ruleStatus=INACTIVE, failureCode=RES_ALLO_FAIL), carried in §5.6.2.19; AF-facing half is TS 29.514 §4.2.5.8	AF half lands with MR 2. Not a quick fix — correlation is keyed on decision version, which these reports don't carry, and the 30 s rollback-tracker TTL is likely shorter than the SMF's round-trip to the RAN.

Accepted — remain until a future refactor, feature, or upstream fix

Limitation	Why it stays
No cross-service PCC-rule conflict detection/resolution (§2.2)	Collision avoidance is by construction (id prefix + reserved precedence band). Active detection, an SM-side band, and a policy for when an AF rule outranks a base rule are all unbuilt.
Precedence can leave its reserved band	Allocated as 1000 + <monotonic uid>, so past 1000 rules it exceeds 1000-1999. Harmless today (nothing enforces the SM-side band either).
No slice-level resource admission control (§2.4)	No slice pools, bandwidth accounting or exhaustion handling. The only capacity gate is the per-session cumulative non-GBR vs. Session-AMBR check.
No TS 23.503 §6.1.3.7 pre-emption-based conflict handling	Over-limit requests are rejected (403), never resolved by pre-empting a lower-priority service.
Compensating rollback is reference-blind, and the rollback path skips validation	A key is reverted only if unchanged since the commit — correct per key, but decided per key rather than as a consistent set. If a commit created a QosData plus a PccRule referencing it and another writer later changed only the rule, the rollback removes the QosData and skips the rule, leaving a dangling reference — and perform_compensating_rollback()'s derive does not call validate_policy_decision() (unlike the POST/PATCH derives), so that decision is committed and sent to the SMF. Needs the pre-notification gate on the rollback path plus a reference-aware pruning pass. Requires concurrent writers and a confirmed permanent rejection, so it is rare today and largely masked by the 408 row below; expect it to become reachable once that is fixed.
Binding by UE IPv4/SUPI only	DNN-based binding not implemented.
PartialSuccessReport read shallowly	Only the top-level failureCause routes retry-vs-rollback, so a partial failure is attributed to the whole commit rather than the rules the SMF named. TS 29.512 §4.2.3.16; types at §5.6.2.27 / §5.6.3.8 / §5.6.3.9.
resPrio → ARP priorityLevel not mapped	Blocked twice over: the generated ReservPriority model is empty (an upstream oai-cn5g-common-src generator defect, not introduced here), and TS 29.513 Table 7.3.2-1 leaves the mapping itself undefined ("application specific algorithm"). preemptCap/preemptVuln are unaffected.
minDesBwDl/Ul not read	Gated behind the IMS_SBI feature (TS 29.514 Table 5.8-1), which this PCF does not negotiate — and that feature also covers unrelated charging behaviour.
desMaxLoss not read	Carries QoSHint/FLUS applicability, also unnegotiated, and the spec prescribes no mapping formula. Should be taken on together with desMaxLatency (read today as best-effort under the same gate).

Checklist

• Code follows project coding standards.
• Relevant tests have been added or updated. (247 GoogleTest cases across 20 suites + the end-to-end lifecycle script; see Tested Environment)
• Documentation has been updated where necessary. (CHANGELOG.md, docs/FEATURE_SET.md — N5 now partially supported, N7 UpdateNotify supported — and ci-scripts/tests/README.md for the new lifecycle script)
• Configuration changes have been validated in the target environment(s). (exercised live via the docker-compose stack above)

Log files or packet captures (PCAPs)

Additional Notes

The QoS feature on PCF is split into three MRs.

Why the split, and why these seams. The original branch carried four phases plus persistence in ~40 commits — not reviewable in one pass. Each MR is cut where the code already has a seam, so none leaves a half-built abstraction:

• MR 1 (this MR) — everything needed to decide and enforce QoS: N5 in, N7 out, correct under concurrency and under SMF rejection. Independently deployable; the AF simply gets no asynchronous notifications.
• MR 2 — hangs off call sites this MR establishes: notify_af_qos_update_failed(), setup_qos_monitoring(), the commented-out AF/monitoring signal typedefs in pcf_event_sig.hpp, and the af()/mon() aspect slots reserved on app_session.
• MR 3 — swaps the crud_store backend injected in pcf_app.cpp against this MR's app_session_record. Last on purpose: the schema should be shaped by all the state Phases 3-4 add, not migrated twice.

[phineSte]

Sequence chart from GitLab MR

sequenceDiagram
    participant AF as Application Function
    participant API as api-server
    participant PA as pcf_policy_authorization.cpp
    participant EVENT as pcf_event.hpp
    participant SMPC as pcf_sm_policy_control.cpp
    participant ASSOC as individual_sm_association.cpp
    participant QOS as app_session.cpp
    participant SMF as SMF

    AF->>API: HTTP POST /app-sessions
    Note over AF,API: AppSessionContext with MediaComponent containing qosReference

    API->>PA: post_app_sessions_handler(context, app_session_id, problem_details)

    
    Note over PA,ASSOC: Session Binding - locate N7 SM Policy association
    PA->>EVENT: sm_session_binding(ueIpv4, supi, dnn, association_id, current_decision)
    EVENT->>SMPC: handle_session_binding_request(ipv4, supi, dnn, assoc_id, decision)
    SMPC->>SMPC: m_policy_storage->find_association(ipv4, supi, dnn)
    SMPC->>ASSOC: get_sm_policy_decision_dto()
    ASSOC-->>SMPC: SmPolicyDecision (base N7 decision)
    SMPC-->>PA: association_id and current_decision populated as out params


    Note over PA,QOS: QoS Parameter Processing
    PA->>PA: authorize_service_info(reqData)

    loop For each MediaComponent where qosReferenceIsSet()
        PA->>QOS: handle_qos_requirements(current_decision)
        QOS->>QOS: create_qos_data_from_media_component(current_decision)
        QOS->>QOS: create_qos_characteristics(current_decision)
        QOS->>QOS: setup_qos_monitoring(current_decision)
        QOS-->>PA: handler_result OK
        PA->>PA: qos_flow_processed = true
    end

    PA->>QOS: validate_qos_authorization()
    QOS-->>PA: handler_result OK

    PA->>PA: validate_and_merge_decision(request_decision, current_decision)
    PA->>PA: app_session(reqContext, current_decision, app_session_id)
    PA->>PA: m_app_sessions.insert(app_session_id, app_session)


    Note over PA,SMF: Cross-Service Coordination and SMF Notification
    PA->>EVENT: sm_update_decision(association_id, current_decision)
    EVENT->>SMPC: handle_update_decision_request(association_id, decision)
    SMPC->>ASSOC: set_sm_policy_decision(decision)
    Note over ASSOC: association now stores SmPolicyDecision with qosDecs and pccRules
    SMPC->>SMPC: send_sm_policy_control_update_notify(association)
    SMPC->>SMF: HTTP POST notificationUri/update with smPolicyDecision containing pccRules and qosDecs
    alt 200 OK
        SMF-->>SMPC: 200 OK
    else 4xx or 5xx
        SMF-->>SMPC: error response, propagated to AF
    end


    Note over PA,AF: AF Notification Infrastructure
    PA--xAF: notify_af_qos_status()
    Note over PA,AF: send Npcf_PolicyAuthorization_Notify to AF callback URI on QoS status changes


    Note over SMPC,SMF: Phase 4 - QoS Monitoring Framework
    SMPC--xSMF: configure QosMonitoringData thresholds
    Note over SMPC,SMF: rovision QosMonitoringData to SMF and deliver measurement reports to AF


    PA-->>API: status_code::CREATED
    API-->>AF: 201 Created Location /app-sessions/{app_session_id}

Loading

[phine-lukas]

It seems a second common-src was added by mistake.

[openairinterface-bot]

CI Build: #22 | Failed on the following stages:

• Prepare Source Metadata

Git operation failure or internal CI error

[openairinterface-bot]

CI Build: #26 | Failed on the following stages:

• Prepare Source Metadata

Git operation failure or internal CI error, likely conflicts with develop; please resolve it.

[openairinterface-bot]

CI Build: #29 | Failed on the following stages:

• Prepare Source Metadata

Git operation failure or internal CI error, likely conflicts with develop; please resolve it.

[sgarg00]

@tariromukute @phine-lukas please rebase your branch on latest develop and resolve any merge conflicts.
Thanks!!

[openairinterface-bot]

CI Build: #30 | Failed on the following stages:

• Code Formatting Checker

[openairinterface-bot]

CI Build: #31 | Failed on the following stages:

• Ubuntu Image with LTTNG Builder

[openairinterface-bot]

CI Build: #32 | Failed on the following stages:

• Testing the tutorials

[openairinterface-bot]

CI Build: #33 | Failed on the following stages:

• Testing the tutorials

[openairinterface-bot]

CI Build: #34 | Failed on the following stages:

• Code Formatting Checker

Validation: SHA recognized in 99a0222, using "origin/feat-n5-qos-support" as branch name
The following commit(s) are missing a Signed-off-by:

99a0222

Please use 'git commit -s' or 'git commit --signoff' to sign your commits.

For detailed instructions, refer to the CONTRIBUTING file at the root of this repository.