Skip to content

Implementation Details

Execution guidance for OSCP 2.0, tying protocol semantics to transport, validation, and operational practices.

Protocol

  • Message types: Register, Handshake/HandshakeAcknowledge, Heartbeat, Update/Adjust Group Capacity Forecast, GroupCapacityComplianceError, UpdateGroupMeasurements, UpdateAssetMeasurements (see api.md for URLs and cardinalities).
  • Format: HTTPS + JSON for all OSCP traffic; Content-Type: application/json; success is HTTP 204 with an empty body.
  • Auth: token per party in the Authorization header on every request; rotate after compromise or registration changes.
  • Segmentation: use X-Segment-Index and X-Segment-Count on all segments; concatenate in index order; first segment correlates to the originating request, subsequent segments correlate to the previous segment.
  • Idempotency: carry X-Request-ID on every call and X-Correlation-ID on responses/segments to bind retries.

Error Handling

  • HTTP 204 is the only success status; error responses use standard HTTP codes and may include a JSON body with message. Include X-Correlation-ID to link errors back to originating requests.
  • Reject invalid schema/enum/cardinality values with HTTP 400 and a short diagnostic message.
  • If FP cannot meet a forecast, send GroupCapacityComplianceError and expect HTTP 409 handling on the CP side.
  • Common faults and responses:
  • Registration: HTTP 501 when no OSCP version overlap; invalidate old tokens after successful registration.
  • Handshake: HTTP 400 when preferences or acknowledgements are rejected.
  • Segmentation: every segment must carry X-Segment-Index and X-Segment-Count; reassemble in index order.
  • Offline handling: missing heartbeats trigger FCC/FGC fallback until handshake succeeds again.
  • Idempotency & correlation: use X-Request-ID for uniqueness and X-Correlation-ID for responses/segments; align heartbeat and retry windows so retries do not push a party into offline state.
  • Error taxonomy:
Scenario HTTP Body / Code Client Action
Unsupported OSCP version during Register 501 { "message": "Version not supported" } Stop; retry with supported version or abort onboarding.
Invalid payload (schema/enum/cardinality) 400 { "message": "Validation failed" } Fix payload; include X-Request-ID for tracing.
Unauthorized (bad/missing token) 401 { "message": "Unauthorized" } Refresh token out-of-band; retry with valid Authorization header.
Forbidden (wrong direction/role) 403 { "message": "Forbidden" } Correct endpoint/direction; confirm role expectations.
Too many requests 429 { "message": "Rate limit exceeded" } Back off with jitter; respect published limits.
Capacity non-compliance 409 Optional GroupCapacityComplianceError payload Follow fallback plan; CP may adjust forecasts.
Server error 500/502/503 { "message": "Temporary failure" } Retry with exponential backoff; stop after N attempts, alert operators.

Security

  • Transport: HTTPS with JSON payloads; use TLS server certificates for all endpoints (TLS 1.2+; modern ciphers).
  • Authentication: token in Authorization header for every request; exchange tokens out-of-band during registration and rotate on a defined cadence (e.g., 90 days) or after compromise.
  • Identity scope: Registration/handshake establish which base URLs and versions are trusted; invalidate previous tokens once new ones are active.
  • Logging & traceability: include X-Request-ID on all messages and X-Correlation-ID on responses/segments to enable end-to-end tracing; avoid logging tokens.
  • Privacy: payloads focus on operational energy data; avoid embedding personal information in identifiers.
  • Fallback posture: when offline, operate within FCC/FGC values to avoid unsafe grid impact until a new handshake confirms state.

Deployment

  • Environments & endpoints:
Environment Base URL (example) Notes
Dev/Sandbox https://dev.example.com/oscp/fp/2.0 Looser rate limits; wider logging.
Test/UAT https://uat.example.com/oscp/fp/2.0 Mirrors production headers and timeouts.
Production https://prod.example.com/oscp/fp/2.0 Locked-down IPs, alarms on heartbeat loss.
  • All endpoints extend the registered base URL (e.g., /handshake, /heartbeat, /register); Register is always <base>/register.
  • Registration: each party generates a token and exchanges it out-of-band with its base endpoint. POST initiates registration; PUT updates the endpoint; DELETE unregisters and stops communication. Replace temporary tokens after successful registration.
  • Handshake: negotiates heartbeat interval and required behaviour (e.g., measurement_configuration). CP → FP (or FP → CO) initiates; receiver returns HTTP 204 and then HandshakeAcknowledge. Only after a successful handshake may other OSCP messages flow.
  • Connectivity: OSCP runs over HTTPS + JSON; parties initiate outbound HTTPS per role (CP → FP/CO; FP → CP/CO). Agree heartbeat frequency to balance detection speed vs traffic overhead. Use TLS server certs; mTLS not required, token auth is mandatory.
  • Segmentation & payload size: use segmented messages with X-Segment-Index and X-Segment-Count on every segment; concatenate in index order. First segment correlates to the originating request; subsequent segments correlate to the previous segment.
  • Dependencies: upstream/downstream network direction is outlined in topology.md; ensure egress allows outbound HTTPS to counterparts.

Monitoring

  • Liveness & offline detection: infer offline state from missed heartbeats, missing capacity forecasts, or missing metering values. Heartbeats carry offline_mode_at; if none arrive before that time, declare the sender offline. Heartbeats must be more frequent than any other OSCP message type.
  • Offline & fallback: when CP is offline, FP applies FCC/FGC until a handshake succeeds again. After CP returns and handshakes, FP restores normal capacities and resumes standard forecasts.
  • Metering discipline: FP must send aggregated measurements to CP and, when applicable, asset-level measurements to CO. CP lowers capacity to a safe value if metering visibility is lost. Align metering frequency with heartbeat/offline thresholds to avoid false positives.
  • Health, metrics, alerts:
  • Health: HTTP reachability of /heartbeat and timely offline_mode_at updates; alert on heartbeat gaps > negotiated interval.
  • Metrics: heartbeat latency and miss count; forecast delivery latency; measurement ingestion success rate; segmentation rate; error rate by endpoint.
  • Runbooks: heartbeat misses trigger offline fallback and page on-call if beyond 2× interval; schema/validation failures logged with request IDs and rejected with 400; capacity compliance errors alert operators with violating blocks.

Validation

  • JSON Schemas for payload validation sit in schemas/index.md and are bundled into the site as /schemas/*.json; copy alongside deployments for contract testing.