Micro Runtime Cleanup 3: Add service lastError() and centralize runtime error recording #73

Activity

1. matkomat

   added

   enhancementNew feature or requestNew feature or request

   priority:P1High-priority parity or behavior gapHigh-priority parity or behavior gap

   area:microMicro/service frameworkMicro/service framework

   on Mar 30, 2026
2. matkomat commented on Mar 31, 2026

   

   matkomat

   on Mar 31, 2026

   ContributorAuthor

   More actions

   Implementation plan for whoever picks this up:

   Goal

   • Add first-class service runtime error visibility through Service::lastError().
   • Introduce one internal recordError() path inside the micro service layer.
   • Keep this issue narrowly scoped to error recording and observability.
   • Start from main, not from PR fix: tighten micro service semantics #70 or any follow-up branch.

   Target API after this issue

   Public service API should gain:

   • ServiceInterface::lastError(): ?\Throwable
   • Service::lastError(): ?\Throwable

   Internal service behavior should gain:

   • a private ?\Throwable $lastError field in Service
   • a private recordError(\Throwable $e): void helper that:
     • stores the latest error on the service
     • invokes the configured errorHandler, if present
     • swallows exceptions thrown by the user-provided errorHandler

   Scope

   Touch only what is needed for this issue:

   • src/Micro/Service.php
   • src/Micro/ServiceInterface.php
   • tests/Integration/Micro/ServiceTest.php
   • tests/Integration/Micro/StatsHandlerTest.php only if needed for shared assertions or compile fallout

   What should change in Service behavior

   1. Handler exceptions

   • When an endpoint handler throws, the service should still update endpoint stats as today.
   • In addition, it should call recordError($e) so callers can inspect lastError().

   2. Response-send failures

   • If the service tries to send an automatic micro error response and that send fails, that send failure must also reach recordError().
   • This issue is about observability only. Do not solve duplicate-reply suppression here; that belongs to Micro Runtime Cleanup 5: Keep single-reply enforcement inside the micro layer #75.

   3. User error handlers

   • If ServiceConfig::errorHandler itself throws, that must not replace or erase the original runtime failure.
   • The original service runtime failure remains the one stored in lastError().

   Test changes

   Add or port focused integration coverage for these paths:

   • handler failure is exposed through lastError() and endpoint stats
   • a throwing user errorHandler does not break the main error flow
   • response-send failure becomes observable through lastError()

   Preferred naming direction:

   • testHandlerFailureIsExposedThroughLastErrorAndStats
   • testThrowingErrorHandlerDoesNotBreakErrorFlow
   • testResponseSendFailureIsObservable

   Do not add tests here for:

   • reset() semantics
   • control-subject callback hardening
   • graceful stop() / deferred cleanup
   • duplicate-response behavior after a successful reply

   Those belong to later issues.

   Explicit non-goals / forbidden changes

   • do not modify src/Message.php
   • do not modify src/Micro/RequestInterface.php
   • do not introduce hasResponded() or any duplicate-reply bookkeeping here
   • do not refactor Service::stop() here beyond trivial compile fallout, if any
   • do not change control-subject callback evaluation order here; that belongs to Micro Runtime Cleanup 6: Harden control-subject callbacks and throwing stats handlers #76
   • do not refresh README or examples here; that belongs to Micro Runtime Cleanup 8: Refresh micro docs and examples after the API cleanup #78

   Acceptance checklist

   • ServiceInterface exposes lastError(): ?\Throwable
   • Service stores and returns the latest runtime error
   • handler exceptions update both endpoint stats and lastError()
   • automatic error-response send failures update lastError()
   • a throwing configured errorHandler does not break the main runtime error path
   • no unrelated lifecycle or API cleanup work is folded into this PR

   Suggested verification

   • vendor/bin/phpunit tests/Integration/Micro/ServiceTest.php
   • vendor/bin/phpunit tests/Integration/Micro/StatsHandlerTest.php if touched

   Review notes

   The review for this issue will check specifically for:

   • accidental scope drift into stop(), reset(), or control-subject hardening
   • any src/Message.php edits
   • duplicate-reply logic being introduced too early
   • whether lastError() truly reflects the original runtime failure when errorHandler also throws