Status endpoint requirements for CAEP interop profile

[thomasdarimont]

This topic should address the discussion on the requirements for the status endpoint for the CAEP interoperability profile.

[jischr]

Stream Status 8.1.2
Event Streams are managed independently. A Receiver MAY request that events from a stream be interrupted by Updating the Stream Status (Section 8.1.2.2). If a Transmitter decides to enable, pause or disable updates from a stream independently of an update request from a Receiver, it MUST send a Stream Updated Event (Section 8.1.5) to the Receiver.

The Profile mentions
Stream Verification
A Receiver MUST be able to verify the liveness of the Stream by requesting that the Transmitter send it a Stream Verification event by providing a valid authorization
This is a bit vague, perhaps we can reiterate what is in SSF. This section is getting distorted with the Receiver's ability to read a stream’s status by making a HTTP GET request to the stream's Status Endpoint. The Transmitter MUST support this.

Profile Addition?
As defined in Section 8.1.2, If a Transmitter decides to enable, pause or disable updates from a stream independently of an update request from a Receiver, it MUST send a Stream Updated Event to the Receiver. (It MUST also be able to to receive an update request from a Receiver and update the status of a stream accordingly. - this needs clarification with section on Updating/Replacing a Stream’s Configuration)

What operations count as "activity" for poll-based streams?
How should Receivers react to streams disabled due to inactivity?

[appsdesh]

I'd like to share our perspective on the proposal to remove the status endpoint requirement from the CAEP interoperability specification. After consideration, I support its removal and believe it is not essential for achieving our primary goal of interoperability.

Here is the reasoning:

• Reduced Specification Complexity - Every endpoint and requirement added to a specification increases its overall complexity, making it harder to understand, implement correctly, and test. A leaner spec accelerates adoption. We can always update this if we hear any feedback, Okta has been onboarding partners from late 2023 and no partners indicated the need for status endpoint so far.

• Core Goal of Interoperability: The primary objective of the interop spec should be to define the bare minimum, yet enterprise-ready, set of requirements for sharing signals reliably. While a status endpoint can enable valuable observability use cases, it is not a fundamental prerequisite for two parties to demonstrate interoperable signal sharing.

• Existing Mechanisms are Sufficient: We already have mechanisms within the specification to verify the health of a stream. The verify endpoint allows a receiver to request a verification event, which, upon receipt, confirms the stream is operational. This sufficiently addresses the scenario where a stream is active but has not transmitted events for a period.

• Out-of-Band Error Handling: In cases of event delivery failure, transmitter implementations would typically include robust error notification capabilities. A spike in such errors would signal an unhealthy stream, which can be monitored and managed outside the strict scope of the CAEP interop spec. This aligns with standard operational practices for event-driven systems.

• Remediation with and without status is the same: The logical next step after detecting an unhealthy stream is remediation, such as updating the stream configuration or recreating it. These actions could be taken independet of the status endpoint presence.

This
suggests taking the dependency on the stream status capabilities. We don't have mechanism to indicate whether streams could be in "paused" state. For adding status as a requirement in interop profile, the earlier capability in SSF spec would be a prerequisite.

By keeping the specification focused on the essential components for interoperability, we can lower the barrier to entry for implementers and encourage wider adoption.

[thomasdarimont]

Thanks for the discussion; this helped clarify the trade-offs.

The current conformance tests were built against the CAEP Interop Profile Draft 02, which explicitly requires the Status Endpoint (GET/POST, support for enabled, paused, and disabled). If the WG decides to remove this requirement again, the tests will need to be adjusted accordingly, which is fine with me, but it’s important that the profile and conformance expectations stay aligned.

I agree that requiring the Status Endpoint:

• adds implementation and testing complexity,
• forces transmitters to manage stream state,
• and provides limited additional interoperability guarantees given the lack of standardized capability signaling or pause semantics (e.g., buffering guarantees).

Given that, I think this is a reasonable time to apply the “when in doubt, leave it out” principle to the base CAEP Interop profile to have minimal interop guarantees.

One possible way forward (if useful to the WG):

• keep the base CAEP interop profile minimal (no mandatory Status Endpoint),
• and optionally define additional stream control requirements (status/pause, deletion (*)) as a separate capability or profile extension.

From a conformance perspective, that would allow status-related tests to be clearly scoped and avoid encoding assumptions that SSF intentionally leaves unspecified.

Happy to realign the tests once the WG direction is clear.

*) According to section 2.3.8.2 Stream Control stream deletion is also not part of the CAEP Interop profile, and therefore the "delete and recreate" approach that was suggested in the WG call is currently not covered by CAEP Interop as well. But this is probably worth a separate issue.

[tulshi]

Adding @traib-google 's post on the mailing list:

Discussed this internally with the Google Workspace SSF team, we'd like to recommend a mix of 2. and 3. for certification - reading + updating iff pauses are supported.

Rationale
I tried to keep this brief, though please let me know if I should expand on any points, happy to do so.

Certification tends to apply "impementation pressure", in both directions. The set of features included in the certification is strictly adhered to, at the same time there is less incentive to go beyond. E.g. if reading or updating the stream status is not included, a Transmitter may validly decide not to implement them at all, and Receivers need to find a workaround that's certified instead.

Reading is straightforward, as there is literally no alternative to getting the status of a stream. It is important for observability - monitoring the continued health of a stream, debugging if event are not being received etc.

Updating is a bit more nuanced.

Pause: As per my reading of the spec, the only two ways to pause a stream is 1. if the Transmitter does it on its own or 2. if the Receiver requests it using the Stream Update endpoint.

So
If a stream is paused the only way to unpause it is to update the stream.
If we compel Transmitters to implement Stream Update, we are indirectly forcing them to implement pausing/unpausing as well. (Or we could soften the language in the SSF spec to say that pausing is optional and can be rejected. But that does complicate Stream Update.)
For certification the suggestion would be - If a Transmitter supports pauses, it must also have a Stream Update endpoint.

Disable: Without update, Receivers would need to implement extra logic to disable the stream (alternative - delete) and reenable the stream (alternative - delete + recreate).

Saving the stream connection information but disabling it for a bit is a useful feature for admins. Whether the burder should be on the Transmitter or the Receiver in this case is up to the ecosystem.

[thomasdarimont]

In todays SSF WG call we discussed the status endpoint requirement for the CAEP Interop spec again.
It was agreed to keep support for "Reading the stream status" in the CAEP interop profile.

The WG will update the section 2.3.5. Status Endpoint accordingly.