# Proposers - Lluis Gifre (CTTC) # Description Add controller-authoritative discovery of optical path and spectrum candidates for optical connectivity services. The feature lets an external orchestrator ask TFS for feasible optical routes and flex-grid spectrum blocks before creating a service. TFS must remain the source of truth: the Optical Controller computes optical feasibility, path candidates, required spectrum width, and slot availability from controller inventory and optical state. The external system may provide high-level service intent, endpoint references, capacity, modulation hints, preferred band or slot range, and policy constraints, but it must not be responsible for inventing the final optical path or deciding whether spectrum is available. The resulting candidates are intended to feed distributed spectrum negotiation and the existing optional spectrum reservation workflow. # Demo or definition of done The feature is complete when TFS can: - receive a candidate request for an optical connectivity service between two optical endpoints or remote-domain abstraction endpoints; - derive the required optical spectrum from connection specifications in the Optical Controller; - compute one or more candidate optical paths using the current Optical Controller path/RSA logic; - return candidate paths as ordered optical link and endpoint hops; - return candidate spectrum ranges that satisfy continuity and contiguity across every optical link in each path; - filter out ranges already occupied by active optical allocations or non-expired reservations; - optionally honor preferred band, preferred slot range, disjointness, max-hop, or routing constraints when feasible; - explain rejection causes when no path or no contiguous spectrum is available; - let NBI expose the candidate result through TFS-API; - let Service consume a selected candidate or reservation during optical service provisioning without changing the existing no-candidate/no-reservation behavior; - pass unit and integration tests covering available path, unavailable path, occupied spectrum, reserved spectrum, invalid endpoints, preferred-range success, and preferred-range rejection. ## Acknowledgements This work is funded by the European Commission through the HORIZON-JU-SNS-2023 PROTEUS-6G project with Grant Agreement number 101139134. # References 1. ETSI TeraFlowSDN Context model: `proto/context.proto`. 2. TeraFlowSDN Optical Controller RSA logic: `src/opticalcontroller/RSA.py` and `src/opticalcontroller/tools.py`. 3. TeraFlowSDN Optical Controller northbound routes: `src/opticalcontroller/OpticalController.py`. 4. TeraFlowSDN Service two-step lifecycle: `CreateService` followed by `UpdateService`. 5. TeraFlowSDN optical spectrum reservation feature: Context/NBI/Service/Optical reservation lifecycle. # Feature Design (for New-Features) ## Clarifications to Expected Behavior Changes Today, optical service provisioning computes the optical route and spectrum inside the Optical Controller as part of service provisioning. That behavior should remain the default and must keep working when no candidate or reservation reference is provided. The new behavior adds a pre-provisioning candidate-discovery operation. It is a read-only or prepare-only operation unless the caller explicitly asks to reserve one returned candidate through the reservation feature. The Optical Controller remains the component that computes optical paths and spectrum feasibility because it already owns the optical-specific RSA logic and slot-state interpretation. Expected behavior changes: - External systems can ask TFS for feasible optical path and spectrum candidates before service creation. - Candidate computation uses controller inventory and optical slot state, not external cached topology. - Candidate computation can consider existing active optical allocations and active spectrum reservations. - Candidate results include enough evidence for explainable negotiation: endpoint hops, optical links, band, slots, required width, and rejection reasons. - The caller may request that one candidate is reserved by TFS, but reservation persistence and conflict protection remain handled by the existing reservation logic. - Service may later receive a selected candidate or reservation reference during `UpdateService`. - If no candidate or reservation is provided, Service and Optical use the existing provisioning behavior. This feature should avoid moving optical intelligence to upper layers. Upper-layer modules can negotiate, rank, explain, and select among TFS-provided candidates, but TFS must validate that the selected path and spectrum are still feasible before provisioning. ## References - `context.proto`: topology, optical links, optical link slot maps, optical spectrum reservations. - `src/opticalcontroller/RSA.py`: current optical route and spectrum assignment logic. - `src/opticalcontroller/tools.py`: bitrate-to-slot and slot-selection helper logic. - `src/opticalcontroller/OpticalController.py`: current optical controller API surface. - `src/service/service/ServiceServiceServicerImpl.py`: service update/provisioning entry point. - `src/nbi/service/tfs_api/Resources.py`: REST TFS-API resource mapping. ## Assumptions - The spectrum reservation persistence/exposure feature is implemented or will be available before candidate reservation is required. - Optical services continue to use the two-step lifecycle: - `CreateService` reserves only service UUID/name/type. - `UpdateService` provides endpoints, constraints, and config rules, then triggers provisioning. - The Optical Controller is the current authority for optical path computation and RSA. - The first implementation can expose candidate discovery for optical connectivity services only. - Packet/L2/L3 service composition is out of scope for this feature. - Remote-domain abstraction endpoints may be treated as optical endpoint-like nodes when they are modeled that way in the topology. - Candidate results are advisory until reserved or consumed. - A candidate selected by an external system must be revalidated by TFS immediately before reservation or provisioning. - `tfs-ctrl` implementation changes must be reviewed and manually committed by the project owner. ## Impacted Components - Optical Controller - Context - NBI/TFS-API - Service - PathComp - Tests/CI ## Optical Controller Impact The Optical Controller should expose an internal operation that computes feasible optical connectivity candidates from service-level inputs. This operation should wrap or refactor existing RSA logic rather than duplicating path computation elsewhere. Recommended internal request: ```text ComputeOpticalConnectivityCandidates - context_id - topology_id - src_endpoint_id - dst_endpoint_id - capacity_gbps optional - modulation_format optional - explicit_channel_width_ghz optional - preferred_band optional - preferred_n_start optional - preferred_n_end optional - max_candidates optional - max_hops optional - routing_constraints optional - exclude_optical_link_ids optional - include_reserved_slots boolean default false ``` At least one of these input sets must be present: ```text capacity_gbps + modulation_format explicit_channel_width_ghz ``` The Optical Controller should derive the required slot count using its own optical logic. If existing functions only map bitrate to slots, they should be extended to handle modulation or explicit channel width in a controlled way. External systems should not send arbitrary slot counts as authoritative input. Recommended internal response: ```text OpticalConnectivityCandidateReply - candidates repeated - rejected_reasons repeated - required_slots - effective_channel_width_ghz - request_summary ``` Recommended candidate object: ```text OpticalConnectivityCandidate - candidate_uuid - path_hops repeated - optical_link_ids repeated - band - n_start - n_end - required_slots - available_slots_summary - occupied_conflicts repeated - reservation_conflicts repeated - path_metric optional - estimated_distance_km optional - validation_status ``` Path hops should be ordered and should include endpoint IDs when available: ```text OpticalPathHop - sequence - ingress_endpoint_id optional - optical_link_id - egress_endpoint_id optional - device_id optional ``` Candidate computation must enforce: - endpoint existence and compatibility; - optical reachability between source and destination; - path continuity; - spectrum contiguity within each optical link; - spectrum continuity across all optical links in the candidate path; - exclusion of slots occupied by active optical allocations; - exclusion of slots held by active, non-expired reservations unless explicitly requested for diagnostics; - preferred band/range validation when provided. The Optical Controller should provide rejection reasons that are precise enough for operators and orchestration workflows: ```text INVALID_ENDPOINT NO_OPTICAL_TOPOLOGY NO_PATH INSUFFICIENT_CONTIGUOUS_SPECTRUM PREFERRED_RANGE_OCCUPIED PREFERRED_BAND_UNAVAILABLE UNSUPPORTED_CAPACITY_OR_MODULATION RESERVATION_CONFLICT ``` ## Context Impact Context should remain the persistence source for topology, optical links, slot state, and reservations. This feature does not require Context to compute paths. Context should provide efficient reads needed by the Optical Controller: - get topology optical link IDs; - get optical link details for a set of optical links; - get active optical spectrum reservations for a context/topology; - get service/connection allocation state that affects slot occupancy. If existing Context APIs do not expose enough information to the Optical Controller, add component-level gRPC methods rather than forcing Optical to reconstruct state from NBI responses. Context may optionally persist candidate records for audit/debugging, but persistence is not mandatory for the first implementation. If candidates are persisted, they must have short TTLs and must be marked advisory, not authoritative reservations. ## NBI/TFS-API Impact NBI should expose candidate discovery through TFS-API for external orchestrators. Recommended REST endpoint: ```text POST /tfs-api/context/{context_uuid}/topology/{topology_uuid}/optical-connectivity-candidates ``` Recommended request: ```json { "src_endpoint_id": { "device_uuid": "DC1-TP1", "endpoint_uuid": "DC1-TP1/LINE" }, "dst_endpoint_id": { "device_uuid": "DOMAIN-B", "endpoint_uuid": "DOMAIN-B/port-out" }, "capacity_gbps": 100, "modulation_format": "DP-QPSK", "preferred_band": "c_slots", "preferred_n_start": 0, "preferred_n_end": 15, "max_candidates": 3 } ``` Recommended response: ```json { "required_slots": 16, "effective_channel_width_ghz": 100, "candidates": [ { "candidate_uuid": "candidate-...", "band": "c_slots", "n_start": 10, "n_end": 25, "optical_link_ids": ["..."], "path_hops": [ { "sequence": 0, "optical_link_id": "...", "ingress_endpoint_id": "...", "egress_endpoint_id": "..." } ], "validation_status": "VALID" } ], "rejected_reasons": [] } ``` NBI should map validation failures to clear HTTP errors: - `400` for malformed input or unsupported capacity/modulation; - `404` for missing context, topology, endpoint, or optical topology; - `409` for valid request with no feasible candidate due to resource conflicts; - `503` for unavailable Optical Controller or required backend component. For observability, NBI should not hide Optical Controller rejection reasons behind generic errors. ## Service Impact Service should remain backward compatible. Existing behavior: - `UpdateService` has endpoints, constraints, and config rules; - Service triggers optical provisioning; - Optical computes path and spectrum as it does today. New optional behavior: - `UpdateService` may include a reservation reference created from one candidate. - `UpdateService` may include a selected candidate reference if candidate persistence is implemented. - Service forwards the selected reservation/candidate reference to Optical. - Optical revalidates the selected path and spectrum before mutating optical state. - Service must not mark the service `ACTIVE` unless Optical confirms that the final allocation matches the selected reservation/candidate when one is specified. The preferred first implementation is: 1. NBI asks Optical for candidates. 2. External orchestration workflow asks TFS to reserve one candidate. 3. Service receives the reservation UUID during `UpdateService`. 4. Optical consumes the reservation and provisions the service. This avoids making Service responsible for candidate persistence or path validation. ## PathComp Impact PathComp should not become the source of truth for optical RSA if the current optical workflow computes paths in the Optical Controller. Two integration options are possible: - Short-term: Optical Controller computes optical paths internally using its existing RSA logic and Context state. - Future: PathComp exposes optical-path-only candidate routes, and Optical Controller performs spectrum feasibility and candidate filtering over those paths. For the current feature, use the short-term option. It matches existing TFS optical behavior and minimizes disruption. The design should not block a later refactor where PathComp contributes route candidates, but Optical must still own optical spectrum feasibility and final validation. ## Backward Compatibility The feature must be opt-in. Existing optical service creation and deletion flows must behave exactly as before when no candidate or reservation reference is provided. Existing topology descriptors do not need to change. Existing optical controller provisioning APIs may remain, but candidate computation should reuse their internal logic wherever practical. ## Testing Unit tests should cover: - valid endpoint pair returns at least one candidate; - missing source endpoint returns `404`; - missing destination endpoint returns `404`; - unsupported capacity/modulation returns `400`; - preferred range too small returns `400`; - preferred range occupied by optical link state returns `409`; - preferred range held by active reservation returns `409`; - non-preferred request skips occupied/reserved ranges and returns another range; - no optical path returns `409` with `NO_PATH`; - no contiguous spectrum returns `409` with `INSUFFICIENT_CONTIGUOUS_SPECTRUM`. Integration tests should be materialized under `src/tests/spectrum_negotiation/` as executable scripts first, then promoted to CI later. Recommended live validation sequence: 1. Load Domain A optical topology. 2. Request candidates from `DC1-TP1` to `DC2-TP1`. 3. Verify returned path contains ordered optical links. 4. Verify returned spectrum range is contiguous and available on every returned optical link. 5. Reserve the first candidate. 6. Request candidates again and verify the reserved range is no longer returned by default. 7. Create an optical connectivity service using the reservation reference. 8. Verify service reaches `SERVICESTATUS_ACTIVE`. 9. Verify the final optical allocation matches the reserved range. 10. Delete the service. 11. Verify allocation and reservation cleanup.