src/ApplicationBundle/Modules/Api/Controller/EbEventsController.php line 38

Open in your IDE?
  1. <?php
  3. namespace ApplicationBundle\Modules\Api\Controller;
  5. use ApplicationBundle\Controller\GenericController;
  6. use ApplicationBundle\Interfaces\PublicApiInterface;
  7. use ApplicationBundle\Helper\EbBridgeConfig;
  8. use ApplicationBundle\Modules\Api\Support\EbBridgeVerifier;
  9. use CompanyGroupBundle\Entity\EnergyBridgeEvent;
  10. use CompanyGroupBundle\Entity\EnergyBridgeSiteLink;
  11. use Symfony\Component\HttpFoundation\Request;
  12. use Symfony\Component\HttpFoundation\JsonResponse;
  14. /**
  15.  * EB1c — the Energy⇄Business Bridge ingress endpoint (`POST /api/v1/eb/events`). The cloud EMS
  16.  * dispatcher delivers signed, idempotent events here per EB_BRIDGE_CONTRACT_v1.md. This endpoint
  17.  * ONLY lands + dedupes the raw event (no GL, no business posting — that is EB3/EB2, downstream).
  18.  *
  19.  * Design decisions (documented per the track brief):
  20.  *  - The raw event log lives CENTRAL (company_group), keyed by event_id, so dedupe + audit are
  21.  *    global and the endpoint needs no tenant context to accept an event. The resolved tenant
  22.  *    (appId, via the EB0 site-link) is stamped on the row; per-tenant artifacts are created later
  23.  *    by the downstream handlers, which switch to the tenant DB themselves.
  24.  *  - The signing secret being unset is the ingress OFF-switch (503 "not configured") — so the
  25.  *    bridge is inert by default until the owner shares the secret. The per-tenant opt-in
  26.  *    `acc_setting energy_bridge_enabled` (default OFF) gates the downstream BUSINESS action, not
  27.  *    this landing step (we never want to lose an audit event just because a tenant hasn't opted in).
  28.  *  - Fail-safe on an unmapped site_uid: the event is still landed, flagged `unlinked`, and NO
  29.  *    business action is queued — we never post to a guessed tenant.
  30.  *
  31.  * Responses (contract §1): 200 accepted/duplicate; 401 bad signature / stale timestamp;
  32.  * 400 malformed; 503 not configured / transient (producer retries).
  33.  */
  34. class EbEventsController extends GenericController implements PublicApiInterface
  35. {
  36.     const MAX_BYTES = 1048576; // 1 MB cap (DoS guard); EB events are small JSON envelopes.
  38.     public function receiveAction(Request $request)
  39.     {
  40.         // 1. Read the RAW bytes FIRST — the HMAC signature is over the exact body sent.
  41.         $raw = (string) $request->getContent();
  42.         if (strlen($raw) > self::MAX_BYTES) {
  43.             return new JsonResponse(['status' => 'error', 'error' => 'payload too large'], 413);
  44.         }
  46.         // 2. Ingress gate: no shared secret configured → we cannot verify anything. Return 503 so
  47.         //    the producer retries (rather than permanently failing the event) once the owner wires
  48.         //    HONEYBEE_EB_SIGNING_SECRET. This is also the bridge's default-OFF switch.
  49.         $secret = EbBridgeConfig::signingSecret();
  50.         if ($secret === '') {
  51.             return new JsonResponse(['status' => 'error', 'error' => 'bridge not configured'], 503);
  52.         }
  54.         // 3. Verify HMAC-SHA256 over the raw body (constant-time). Mismatch/malformed → 401.
  55.         $sigHeader = $request->headers->get('X-EB-Signature');
  56.         if (!EbBridgeVerifier::verifySignature($raw, $sigHeader, $secret)) {
  57.             return new JsonResponse(['status' => 'error', 'error' => 'bad signature'], 401);
  58.         }
  60.         // 4. Replay window: reject a delivery whose timestamp is outside ±window of server time.
  61.         $now = time();
  62.         if (!EbBridgeVerifier::timestampFresh($request->headers->get('X-EB-Timestamp'), $now, EbBridgeConfig::replayWindow())) {
  63.             return new JsonResponse(['status' => 'error', 'error' => 'stale or missing timestamp'], 401);
  64.         }
  66.         // 5. Decode + validate the envelope (event_id + event_type required).
  67.         $evt = EbBridgeVerifier::decodeEvent($raw);
  68.         if ($evt === null) {
  69.             return new JsonResponse(['status' => 'error', 'error' => 'malformed event'], 400);
  70.         }
  71.         $eventId = $evt['event_id'];
  73.         // 6. Everything below is on the CENTRAL manager (dedupe + audit are global).
  74.         try {
  75.             $em = $this->getDoctrine()->getManager('company_group');
  77.             // 6a. Dedupe: a redelivery of an already-seen event_id is a successful no-op.
  78.             $existing = $em->getRepository('CompanyGroupBundle\\Entity\\EnergyBridgeEvent')
  79.                 ->findOneBy(['eventId' => $eventId]);
  80.             if ($existing !== null) {
  81.                 return new JsonResponse(['status' => 'ok', 'idempotency_key' => $eventId, 'duplicate' => true], 200);
  82.             }
  84.             // 6b. Resolve the tenant via the EB0 site-link (fail-safe: 0 → unlinked, never guessed).
  85.             //     Stamp link_type (self/customer) onto the landed row so EB2/EB3 can branch without
  86.             //     re-reading the map (and so the monitor shows Own vs Customer at a glance).
  87.             $appId = 0;
  88.             $linkType = null;
  89.             if ($evt['site_uid'] !== '') {
  90.                 $link = $em->getRepository('CompanyGroupBundle\\Entity\\EnergyBridgeSiteLink')
  91.                     ->findOneBy(['siteUid' => $evt['site_uid']]);
  92.                 if ($link !== null) {
  93.                     $appId = (int) $link->getAppId();
  94.                     $linkType = $link->getLinkType() ?: EbBridgeVerifier::linkTypeForCustomer($link->getCustomerId());
  95.                 }
  96.             }
  97.             $status = EbBridgeVerifier::statusForAppId($appId);
  99.             // 6c. Land the raw event.
  100.             $row = new EnergyBridgeEvent();
  101.             $row->setEventId($eventId);
  102.             $row->setEventType($evt['event_type']);
  103.             $row->setSiteUid($evt['site_uid'] !== '' ? $evt['site_uid'] : null);
  104.             $row->setOccurredAt(self::parseOccurredAt($evt['occurred_at']));
  105.             $row->setRawJson($raw);
  106.             $row->setSignatureAlg(EbBridgeVerifier::SIGNATURE_ALG);
  107.             $row->setCorrelationId((string) $request->headers->get('X-Correlation-Id') ?: null);
  108.             $row->setStatus($status);
  109.             $row->setAppId($appId > 0 ? $appId : null);
  110.             $row->setLinkType($linkType);
  111.             $row->setReceivedAt(new \DateTime());
  112.             if ($status === 'unlinked') {
  113.                 $row->setNote('no site-link for site_uid=' . $evt['site_uid'] . ' — landed, no business action');
  114.                 error_log('[EB1c] unlinked event ' . $eventId . ' site_uid=' . $evt['site_uid'] . ' type=' . $evt['event_type']);
  115.             }
  116.             $em->persist($row);
  118.             try {
  119.                 $em->flush();
  120.             } catch (\Throwable $flushEx) {
  121.                 // Race: a concurrent delivery of the same event_id won the UNIQUE(event_id) insert
  122.                 // between our find and flush. That is idempotency working — treat as a duplicate.
  123.                 $dupe = $em->getRepository('CompanyGroupBundle\\Entity\\EnergyBridgeEvent')
  124.                     ->findOneBy(['eventId' => $eventId]);
  125.                 if ($dupe !== null) {
  126.                     return new JsonResponse(['status' => 'ok', 'idempotency_key' => $eventId, 'duplicate' => true], 200);
  127.                 }
  128.                 throw $flushEx; // genuine DB error → 5xx below (producer retries)
  129.             }
  131.             return new JsonResponse([
  132.                 'status'          => 'ok',
  133.                 'idempotency_key' => $eventId,
  134.                 'link_status'     => $status,
  135.             ], 202);
  136.         } catch (\Throwable $e) {
  137.             // Genuine transient server error → 5xx so the producer retries with backoff.
  138.             error_log('[EB1c] ingress error for ' . $eventId . ': ' . $e->getMessage());
  139.             return new JsonResponse(['status' => 'error', 'error' => 'temporary server error'], 503);
  140.         }
  141.     }
  143.     /** Tolerant parse of the envelope's occurred_at (a date or datetime); null if unparseable. */
  144.     private static function parseOccurredAt(string $occurredAt): ?\DateTime
  145.     {
  146.         if (trim($occurredAt) === '') { return null; }
  147.         try {
  148.             return new \DateTime($occurredAt);
  149.         } catch (\Throwable $e) {
  150.             return null;
  151.         }
  152.     }
  153. }