Classification
Purpose. Defines the single point where a provider answer (or a transport failure) is turned into a Decision, what the decision asks for (destination and credential actions), the quarantine and invalidation rules, generations, and the explicit environment probe. Sources: docs/PLAN.md §4.4 and §4.5, and src/Core/Outcome/{OutcomeClassifier,ClassifyContext,Decision,DestinationAction,CredentialAction,ReasonCode}.php.
Rules
- One classifier per provider.
OutcomeClassifier::classify(Exchange, ClassifyContext): Decisionis the only code that interprets provider responses or transport failures. The interface docblock states it is pure, total and side-effect free. The implementations areApns\Outcome\ApnsOutcomeClassifier(withApnsReasonCatalog) andFcm\Outcome\FcmOutcomeClassifier(with the FCM reason catalog);Laravel\Testing\FakeClassifieris the test double. - Every possible exchange maps to exactly one
Decision. Unknown provider strings map toReasonCode::Unknownwith the raw string preserved; the classifier never throws. - Listeners and breakers react only to the final
Decision, never to intermediate responses (plan §4.4). ClassifyContextcarries the destination, the binding andvalidateOnly. A 2xx answer to an FCMvalidate_onlyrequest isValidated, notAccepted.- Quarantine is not invalidation. Quarantine suspends the registration in its scope and discards the current send. Invalidation removes the registration as stated by the provider.
- Invalidation applies only to the generation that was attempted (see Generations).
- The environment is never changed during a send (see Environment probe).
Decision fields
| Field | Meaning |
|---|---|
status |
Status if no further attempt is made: Accepted, Validated, Rejected, Failed or OutcomeUnknown. Deferred and Expired are assigned later by the retry planner |
reason |
Reason (code, raw reason, hint) |
retryable |
Whether another attempt is allowed at all; still subject to the budget and the unknown-outcome policy |
minDelaySeconds |
Minimum wait from provider guidance or Retry-After |
destinationAction |
none, quarantine or invalidate |
credentialAction |
none, refresh_token, slow_token_refresh or report_auth_failure |
throttleProvider |
Provider-wide slowdown signal for the shared throttle gate |
invalidatedAtMs |
APNs 410 timestamp in Unix milliseconds |
httpStatus, providerMessageId, meta |
Provider facts, e.g. apns-unique-id in meta |
Destination and credential actions
| Action | Effect (plan) |
|---|---|
DestinationAction::Quarantine |
Current send discarded; registration suspended in its scope; no retry |
DestinationAction::Invalidate |
Registration invalidated, only for the attempted generation |
CredentialAction::RefreshToken |
One coordinated refresh of the provider token for the generation that failed, then one more attempt |
CredentialAction::SlowTokenRefresh |
Slow token renewals; never fail over to the secondary credential for this |
CredentialAction::ReportAuthFailure |
The credential itself is wrong; feeds the authentication breaker, which decides failover once |
Quarantine and invalidation
Public result of a quarantined send: SendStatus::Rejected with ReasonCode::DestinationRejected or DestinationMismatch and DestinationAction::Quarantine (orchestrator’s resolution, README.md). Laravel\Devices\DeviceOutcomeApplier applies the action to the registry: quarantine suspends the device row; invalidation only touches the generation that was attempted and only when the APNs timestamp is later than the registration.
| Provider answer | Destination action (plan §4.4) |
|---|---|
APNs BadDeviceToken (token or environment wrong) |
Quarantine |
APNs DeviceTokenNotForTopic |
Quarantine |
FCM SENDER_ID_MISMATCH |
Quarantine |
APNs 410 Unregistered or ExpiredToken |
Invalidate, only if topic and generation match and the timestamp (Unix ms) is later than the registration |
FCM UNREGISTERED |
Invalidate the destination that was attempted |
FCM INVALID_ARGUMENT |
None. Read error.details; this normally points to the payload |
Code: ReasonCode::DestinationRejected (annotated as APNs BadDeviceToken), DestinationMismatch (annotated as DeviceTokenNotForTopic and SENDER_ID_MISMATCH), DestinationUnregistered (annotated as APNs 410 and FCM UNREGISTERED).
Generations
- A
BindingRefgeneration changes on credential rotation or reconfiguration. ADestinationRefgeneration is the version of the registry row. - A late answer for generation 7 never touches generation 8, even when the raw token is identical (plan §4.4).
- An APNs 410 older than the registration timestamp does not invalidate the current registration.
Environment probe
- The environment of a device is the one the app declared at registration. The send path never switches it.
- The operator runs
mobile-push:devices:probe-environment {--device=} {--quarantined} {--allow-cross-environment}(plan §4.4;Laravel\Console\Ops\ProbeEnvironmentCommandandEnvironmentProber). It sends one silent background push per quarantined device through the connection of the same scope and app on the other environment, one device at a time, and re-labels the registration only when Apple accepts. - Rate limit. A run is capped by
--limit(default 10, at most 100) and a device is contacted at most once perdevices.probe.cooldown_hours(default 24); the time and outcome of the last probe are kept in the device row (metadata.environment_probe).--forcedoes not bypass it;--ignore-cooldowndoes after an interactive confirmation. - Keys bound to one environment. An authentication refusal (
ReasonCode::AuthTokenInvalidwithReportAuthFailure, which is whatBadEnvironmentKeyIdInTokenandBadEnvironmentKeyInTokenmap to; also the otherSTOPScodes ofEnvironmentProber) stops the whole run: no further device is contacted. - The probe asks the safe-mode guard first (
OperationKind::Probe): in simulation nothing is sent.
Types
Outcome\OutcomeClassifier(interface),ClassifyContext,Decision,DestinationAction,CredentialAction,ReasonCode,Reason- Inputs:
Transport\Exchange,Identity\Destination,Identity\BindingRef
Worked cases
A. Wrong environment token.
- Situation: an APNs production send returns
BadDeviceToken. - The package:
DecisionwithDestinationAction::Quarantineand statusRejected. - The caller sees:
Rejected/DestinationRejected, no retry; the registration is suspended in its scope; the environment is not changed. The operator decides with the probe.
B. Old unregistration.
- Situation: APNs returns 410 with a
timestampearlier than the device’s last registration. - The package: no invalidation; the registration stays.
- The caller sees: the failed result for that send. The current registration is untouched.
C. Late answer after re-registration.
- Situation: generation 8 is registered; a response for generation 7 arrives and says 410.
- The package: the invalidation applies only to the attempted generation.
- The caller sees: generation 8 is unchanged, even though the token value is identical.
D. Validate-only success.
- Situation: an FCM request with
validateOnlygets a 2xx. - The package:
Validated, notAccepted. - The caller sees: a result that says the request was validated, not sent.
Plan vs code
- Plan §4.4 says the quarantine response is the “current send discarded” without a
SendStatus; the code makes itRejected(see above). - The two environment-key strings of plan §13 are in the APNs reason catalog (
BadEnvironmentKeyIdInTokenand the reported variantBadEnvironmentKeyInToken, bothAuthTokenInvalidwithReportAuthFailure);ExpiredProviderTokenisAuthTokenExpiredwithRefreshToken(retryable, once);TooManyProviderTokenUpdatesisAuthTokenThrottledwithSlowTokenRefresh. - The
ReasonCodeannotations and the catalog texts are the author’s reading of the provider documentation, not checked against live provider answers.
Open points
- Real-provider verification. The strings of the APNs and FCM catalogs (including the two environment-key variants and
TooManyProviderTokenUpdatesscope) were never compared with real Apple and Google answers. - Behaviour of
ReasonCode::Unknownfor a 5xx that is neither listed nor known: it is kept with its raw string, but whether it should be retried more or less aggressively than a listed 5xx is not decided. - The cooldown (24 h) and the cap (10 per run) of the environment probe are defaults chosen by the package, not values from Apple.
This page is generated from docs/contracts/classification.md. To change it, edit that file in the repository, not this site.