Execution modes and endpoints
Execution modes and endpoints
Purpose. Defines when the package may touch the network, how a live send outside production is authorized, what the three non-network-or-validation outcomes mean, and which hosts a request may reach. Source: docs/PLAN.md §4.6 and the code in src/Core/Policy. The user-facing description is docs/safe-mode.md.
Rules
- Modes.
mode = auto | live | simulate.automeansliveonly whenAPP_ENV=production, otherwisesimulate. Insimulateno network is touched and the status isSimulated. - Live outside production requires both
live.allowon the binding and the destination listed inlive.only_to(test destinations only; the tokens are converted to keyed indexes at load time and never stored raw). - Topics and conditions (
live.allow_topics), broadcast channels (live.allow_broadcast) and channel management (live.allow_channel_management) stay blocked outside production unless explicitly authorized on the binding. - An inconsistency blocks. It never degrades to a live send.
- The check happens before any external effect and covers the CLI, workers, failover, fallback and channel management.
->validateOnly()(FCM) is an authenticated remote call and yieldsValidated.- APNs has no dry run.
previewis local and does not verify credentials.doctor --liveis a real request, and it is described as one. - Official hosts by role (
EndpointRole, resolved byEndpointCatalog), not free URLs: sending, channel management, broadcast publication (connection keybroadcast_host = standard | api-broadcast,ApnsBroadcastHost), and the Google token exchange. TLS and host, CA verification are always on. - Test endpoints (
EndpointOverride) are accepted only when the caller affirms throw-away test credentials and the application environment is not production; origins arehttps://host[:port]with no path. A message cannot name a host. - Every operation is asked first:
SafeModeGuard::decide()takes anOperationKind(Send,Validate,ChannelManagement,BroadcastPublish,TopicSubscription,Probe) and returns aSafeModeDecision. The CLI commands, workers, failover, the environment probe and channel management all go through it. - A blocked live send is
SkippedwithReasonCode::PolicySafeMode; simulation isSimulated(decided at the orchestrator’s resolutions, seeREADME.md).
Status meaning
| Status | Produced when | What it does NOT mean |
|---|---|---|
Simulated |
Mode is simulate; no network touched |
Not sent, not validated |
Validated |
FCM validate_only answered by the provider |
Not sent to the device |
Accepted |
Live send and provider accepted | Not delivered, not seen |
Mode table
mode |
APP_ENV |
Network | Result for a valid message |
|---|---|---|---|
auto |
production |
Yes (live) | Provider result |
auto |
any other | No | Simulated |
live |
any | Yes, subject to the authorization rules | Provider result, or blocked |
simulate |
any | No | Simulated |
Types
Policy\ExecutionMode,ModeResolver(mode andAPP_ENVto live or simulate),SafeModeGuard,SafeModeDecision,OperationKind,LiveSettings(per-bindingallow,only_to,allow_topics,allow_broadcast,allow_channel_management)Policy\EndpointCatalog,EndpointRole,EndpointOverride,ApnsBroadcastHost,CapabilityMatrixOutcome\SendStatus::Simulated,Validated;ReasonCode::Simulated,Validated,PolicySafeMode;ClassifyContext::$validateOnly- Eligibility checks that run before the network live in the Laravel layer (
DeviceEligibility, the consent gates) and inCore\Driver\DestinationGate; there is noPolicy\EligibilityGuardclass.
Worked cases
A. Local development.
- Situation:
APP_ENV=local,mode = auto, a valid send. - The package:
simulate; no connection is opened. - The caller sees:
Simulated.
B. Staging with live allowed, wrong target.
- Situation:
live.allowis on, but the destination is not inlive.only_to. - The package: blocked before any external effect.
- The caller sees:
SendStatus::SkippedwithReasonCode::PolicySafeModeand a hint that names the missing setting.
C. FCM dry run.
- Situation: a message is sent with
->validateOnly(). - The package: an authenticated remote call; the provider validates it and does not send.
- The caller sees:
Validated. This is not a delivery test on devices.
D. Production config inside a sandbox command.
- Situation: a CLI command runs with production configuration in a sandbox.
- The package: no connection is opened (plan §11 requires this).
- The caller sees: a
Skipped(PolicySafeMode) orSimulatedresult, with no network trace.
Plan vs code
- The
Simulated,ValidatedandAcceptedsplit matches the code’s enum docblocks. - Plan §4.6 does not map a blocked live send to a status; the code and the orchestrator’s resolutions do (rule 11).
- The plan did not name the test-override settings: they are
EndpointOverride(used by the test seams of the package), with no config key on purpose.
Open points
- Which of the two Apple broadcast hosts Apple operates for a given app (
broadcast_host): both are documented, the default isstandard, and neither has been exercised against Apple. - Whether
previewmay show the destination host: the command prints the compiled message (headers without authorization, the body, the byte count); it does not print a host. Whether it ever should is not decided. - Everything that touches a real provider (
doctor --live, FCMvalidate_only, channel management) is unverified against Apple and Google.
This page is generated from docs/contracts/modes.md. To change it, edit that file in the repository, not this site.