Micro Runtime Cleanup 1: Slim the public Request API #71

Activity

1. matkomat

   added

   enhancementNew feature or requestNew feature or request

   priority:P2Medium-priority parity or feature gapMedium-priority parity or feature 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

   • Replace the current/public micro request boundary with a smaller handler-facing contract.
   • This issue is API cleanup only. Do not solve duplicate-reply suppression here; that belongs to Micro Runtime Cleanup 5: Keep single-reply enforcement inside the micro layer #75.
   • Do not continue from PR fix: tighten micro service semantics #70's implementation. Start from main and implement the smaller boundary directly.

   Target API after this issue

   RequestInterface should expose only:

   • respond(string $data, ?Headers $headers = null): void
   • respondJson(mixed $data, ?Headers $headers = null): void
   • error(string $code, string $description, string $data = ''): void
   • data(): string
   • headers(): ?Headers
   • subject(): string
   • replyTo(): ?string

   Explicitly remove from the public micro API:

   • msg()
   • hasResponded()

   Request.php should no longer expose those methods publicly either.

   File scope

   Touch only what is needed for this boundary cleanup:

   • src/Micro/RequestInterface.php
   • src/Micro/Request.php
   • tests/Integration/Micro/ServiceExtendedTest.php
   • any micro tests that still directly assert msg() / hasResponded() on your working branch

   Avoid folding in unrelated runtime/lifecycle work from:

   • Micro Runtime Cleanup 3: Add service lastError() and centralize runtime error recording #73 lastError() / shared error path
   • Micro Runtime Cleanup 5: Keep single-reply enforcement inside the micro layer #75 duplicate-reply enforcement
   • Micro Runtime Cleanup 6: Harden control-subject callbacks and throwing stats handlers #76 control-subject hardening
   • Micro Runtime Cleanup 7: Refactor Service::stop() into explicit graceful-drain phases #77 graceful stop refactor

   Test changes

   Replace testRequestMsg() with a test that proves handlers still have enough inbound context without a raw Message.

   Preferred shape:

   • publish a request with payload and at least one header
   • inside the handler capture values from:
     • data()
     • subject()
     • replyTo()
     • headers()?->get(...)
   • send the reply through normal Request::respond()
   • assert the captured values after the request completes

   If your branch already contains a hasResponded() test, remove it rather than preserving that API.

   Explicit non-goals / forbidden changes

   • do not modify src/Message.php
   • do not add a replacement raw-message escape hatch under another name
   • do not add respond hooks/callback plumbing anywhere in the core layer
   • do not refactor src/Micro/Service.php here beyond trivial compile fallout, if any
   • do not refresh README/micro docs beyond minimal fallout; the real docs pass is Micro Runtime Cleanup 8: Refresh micro docs and examples after the API cleanup #78

   Acceptance checklist

   • RequestInterface no longer imports or returns Message
   • public micro handlers cannot obtain a reply-capable raw message from the request API
   • inbound metadata needed by handlers is still available through data(), headers(), subject(), and replyTo()
   • integration tests cover the new boundary and no longer depend on msg() / hasResponded()
   • no new core/micro coupling was introduced

   Suggested verification

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

   Review notes

   The review for this issue will check specifically for:

   • accidental src/Message.php changes
   • replacement escape hatches under a different name
   • unrelated Service.php runtime changes folded into the same PR
3. matkomat

   added 2 commits that reference this issue on Mar 31, 2026

   fix: slim public micro request API (#71)

   8a6badd

   fix: slim public micro request API (#71) (#79)

   4f16540
4. matkomat

   closed this as completedin #79on Mar 31, 2026