Class PushWire
java.lang.Object
com.iizix.server.push.engine.http.PushWire
The version 2 wire vocabulary of
POST /iizi-push/<operation>: the operation names, the member names and the closed error vocabulary of PUSH-WIRE-CONTRACT.md sections 1, 2 and 5, in one place.This class is the server's half of a contract that has two ends. The other half is the WIRE object at the top of common/push/push.js, exposed as izPush.WIRE. PushWireAgreementTest runs the production client under Node and compares what it declares and what it sends with the lists here, so the two ends cannot drift apart unnoticed - which is how version 1's c came to mean three things. Every name the handler reads from a request, writes into a reply or answers as an error code comes from here and nowhere else; a literal wire name anywhere else in this package is a defect.
The lists are ordered as the contract orders them, so that a report or a test failure reads in the contract's order.
- Author:
- Christopher Mindus
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final StringTherecipientsentry that is the broadcast (section 5.6, Ruling 3).static final StringTheCache-Controlof every reply (section 1.2).static final StringThe reserved key ofdatathe server writes (section 6.2).static final String400: the body is not a JSON object, a member is missing, of the wrong type or out of range, orX-iiziis missing or not a UUID on a device operation.static final String403: authenticated, but no group grants the operation's privilege.static final String500: anything else.static final String405: not POST.static final String409: the application is loaded but no transport can be offered for it.static final String400: the serialised notification exceeds section 6.3.static final String400:recipientsis an empty array.static final String400:recipientsis absent.static final String403: production server, request not on a secure port.static final String500: the subscription store failed.static final String401: no or unusableAuthorization, unknown user or wrong password - one code for all of them.static final String404:app_idnames an application this server has not loaded.static final String404: the path names no operation.The thirteen error codes, in the order of section 1.3.static final StringThe device UUID header, required on device operations only (section 1.1).static final StringThe Fetch Metadata header a Browser sets on a fetch, an XHR and a navigation to a potentially trustworthy origin (https, the loopback) and no page script can set or remove: a request carrying it is a Browser's, and its 401 carries no challenge (section 1.3).static final StringThe header a Browser sets on every request that is not a GET or a HEAD, over plain http to any address too, and no page script can set or remove: a request carrying it is a Browser's, and its 401 carries no challenge (section 1.3).static final StringThe members ofdata.iizi: the message ID, the application, the Topic, when it was sent and the push server ID, on both legs; and on the FCM leg only, the section 6.1 object as the caller gave it, without itsdata(ruling of 2026-09-22, CC-PUSH-FCM-MAP finding 2: members mapped to native FCM fields never reach the device's JavaScript, so the content travels once more underdata.iizi; ruling of 2026-09-23, CC-PUSH-P3 RR-11: added byFcmTransport.buildMessageand not atpush, so that the Web Push leg, whose Service Worker decrypts the whole object, keeps its size for the caller).static final StringThe members ofdata.iizi: the message ID, the application, the Topic, when it was sent and the push server ID, on both legs; and on the FCM leg only, the section 6.1 object as the caller gave it, without itsdata(ruling of 2026-09-22, CC-PUSH-FCM-MAP finding 2: members mapped to native FCM fields never reach the device's JavaScript, so the content travels once more underdata.iizi; ruling of 2026-09-23, CC-PUSH-P3 RR-11: added byFcmTransport.buildMessageand not atpush, so that the Web Push leg, whose Service Worker decrypts the whole object, keeps its size for the caller).static final StringThe members ofdata.iizi: the message ID, the application, the Topic, when it was sent and the push server ID, on both legs; and on the FCM leg only, the section 6.1 object as the caller gave it, without itsdata(ruling of 2026-09-22, CC-PUSH-FCM-MAP finding 2: members mapped to native FCM fields never reach the device's JavaScript, so the content travels once more underdata.iizi; ruling of 2026-09-23, CC-PUSH-P3 RR-11: added byFcmTransport.buildMessageand not atpush, so that the Web Push leg, whose Service Worker decrypts the whole object, keeps its size for the caller).static final StringThe members ofdata.iizi: the message ID, the application, the Topic, when it was sent and the push server ID, on both legs; and on the FCM leg only, the section 6.1 object as the caller gave it, without itsdata(ruling of 2026-09-22, CC-PUSH-FCM-MAP finding 2: members mapped to native FCM fields never reach the device's JavaScript, so the content travels once more underdata.iizi; ruling of 2026-09-23, CC-PUSH-P3 RR-11: added byFcmTransport.buildMessageand not atpush, so that the Web Push leg, whose Service Worker decrypts the whole object, keeps its size for the caller).static final StringThe members ofdata.iizi: the message ID, the application, the Topic, when it was sent and the push server ID, on both legs; and on the FCM leg only, the section 6.1 object as the caller gave it, without itsdata(ruling of 2026-09-22, CC-PUSH-FCM-MAP finding 2: members mapped to native FCM fields never reach the device's JavaScript, so the content travels once more underdata.iizi; ruling of 2026-09-23, CC-PUSH-P3 RR-11: added byFcmTransport.buildMessageand not atpush, so that the Web Push leg, whose Service Worker decrypts the whole object, keeps its size for the caller).static final StringThe members ofdata.iizi: the message ID, the application, the Topic, when it was sent and the push server ID, on both legs; and on the FCM leg only, the section 6.1 object as the caller gave it, without itsdata(ruling of 2026-09-22, CC-PUSH-FCM-MAP finding 2: members mapped to native FCM fields never reach the device's JavaScript, so the content travels once more underdata.iizi; ruling of 2026-09-23, CC-PUSH-P3 RR-11: added byFcmTransport.buildMessageand not atpush, so that the Web Push leg, whose Service Worker decrypts the whole object, keeps its size for the caller).static final intThe defaultlimitoflist, and its ceiling.static final intThe defaultlimitoflist, and its ceiling.static final StringThe application ID,*for the server itself (section 2.3).static final Stringsubscriptions,countandlistreply: the number matched.static final Stringsubscribereply: true when a new row was stored; an entry: the creation time.static final Stringpushreply: delivered, in session or to a device.static final Stringresetrequest, administrative: the device UUID; an entry: the device UUID.static final StringA failure: the code fromERRORS.static final Stringkeysreply: the Firebase project ID.static final StringA 409 reply: the FCM transport's reason.static final Stringsubscriberequest, Cordova: the FCM registration token.static final StringAn entry: when the device last presented itself.static final Stringlistrequest: the most entries to return.static final Stringpushreply: subscriptions matched.static final StringA failure: the human text; and thepushreply: the message ID (section 6.2).static final Stringpushrequest: the section 6 content object.static final Stringlistrequest: the first entry to return.static final StringEvery reply: true on success, false on failure.static final Stringpushreply: the tally byDeliveryOutcomename.static final Stringpush,countandlistrequest: who is sent to;pushreply: users resolved.static final Stringunsubscribeandresetreply: the number of rows removed.static final Stringsubscriptionsandlistreply: the entries.static final Stringsubscriptionsreply: the entries whose device is the caller's.static final Stringpushrequest: seconds, section 6.4.static final StringThe Topic,""for the application-level subscription (section 2.4).static final StringAn entry:"vapid"or"fcm".static final Stringpushrequest:high,normalorlow, section 6.4.static final Stringresetrequest, administrative: the user name; an entry: the user name.static final Stringsubscriberequest andsubscriptionsentry: the client's user agent.static final Stringkeysreply: the base64url VAPID public key;subscriberequest, optional: the key a Browser subscription was made under (B-10b).static final StringA 409 reply: the VAPID transport's reason.static final Stringsubscriberequest, Browser: thePushSubscription.toJSON()object.Every member name, in the order above.static final StringSection 5.7: count what a push would match.static final StringSection 5.1: the server keys of an application.static final StringSection 5.8: list what a push would match.static final StringSection 5.6: send a notification.static final StringSection 5.4: remove every subscription of a device.static final StringSection 5.2: register this device's subscription.static final StringSection 5.5: this user's subscriptions.static final StringSection 5.3: remove this device's subscription.The eight operations, in the order of section 5.0.static final StringThetransportvalue of an FCM entry.static final StringThetransportvalue of a VAPID entry.static final StringTheurgencyvalues, section 6.4.static final StringTheurgencyvalues, section 6.4.static final StringTheurgencyvalues, section 6.4.static final StringThe challenge a 401 carries (RFC 7617 section 2.1), except to a Browser's request (HEADER_FETCH_MODEorHEADER_ORIGIN, section 1.3).Method Summary
Modifier and TypeMethodDescriptionentryMembers(boolean withUserAgent) Gets the members of a subscription entry (section 5.5), with or without the user agent (section 5.8 omits it for every caller oflist).static JSONObjectiiziMembers(String messageId, String app, String topic, long sent, String server) Builds the server'sdata.iiziof a send (section 6.2): the ONE place its members are written, called by both writers -PushHttpHandler'spushand the Java API'sPushSendSupport.message- so that the two cannot drift apart (CC-DESIGN-PUSH-APPID-FILTER SV-2).static booleanisDeviceOperation(String operation) Tells whether an operation is a device operation:X-iizirequired and a database user required (section 5.0).replyMembers(String operation) Gets the members of an operation's success reply,okincluded.requestMembers(String operation) Gets the request members an operation reads.
Field Details
OP_KEYS
OP_SUBSCRIBE
OP_UNSUBSCRIBE
OP_RESET
OP_SUBSCRIPTIONS
OP_PUSH
OP_COUNT
OP_LIST
OPERATIONS
M_OK
M_ERROR
M_MESSAGE
A failure: the human text; and thepushreply: the message ID (section 6.2).- See Also:
M_APP_ID
The application ID,*for the server itself (section 2.3).- See Also:
M_TOPIC
The Topic,""for the application-level subscription (section 2.4).- See Also:
M_USER_AGENT
subscriberequest andsubscriptionsentry: the client's user agent.- See Also:
M_VAPID_SUBSCRIPTION
subscriberequest, Browser: thePushSubscription.toJSON()object.- See Also:
M_FCM_TOKEN
subscriberequest, Cordova: the FCM registration token.- See Also:
M_CREATED
subscribereply: true when a new row was stored; an entry: the creation time.- See Also:
M_REMOVED
unsubscribeandresetreply: the number of rows removed.- See Also:
M_DEVICE
resetrequest, administrative: the device UUID; an entry: the device UUID.- See Also:
M_USER
resetrequest, administrative: the user name; an entry: the user name.- See Also:
M_THIS_DEVICE
subscriptionsreply: the entries whose device is the caller's.- See Also:
M_COUNT
M_SUBSCRIPTIONS
M_TRANSPORT
M_LAST_SEEN
M_RECIPIENTS
push,countandlistrequest: who is sent to;pushreply: users resolved.- See Also:
M_NOTIFICATION
M_TIME_TO_LIVE
M_URGENCY
M_MATCHED
M_DELIVERED
M_OUTCOMES
M_OFFSET
M_LIMIT
M_VAPID_PUBLIC_KEY
keysreply: the base64url VAPID public key;subscriberequest, optional: the key a Browser subscription was made under (B-10b).- See Also:
M_FCM_PROJECT_ID
M_VAPID_REASON
M_FCM_REASON
MEMBERS
E_BAD_REQUEST
400: the body is not a JSON object, a member is missing, of the wrong type or out of range, orX-iiziis missing or not a UUID on a device operation.- See Also:
E_PAYLOAD_TOO_LARGE
400: the serialised notification exceeds section 6.3.- See Also:
E_RECIPIENTS_MISSING
E_RECIPIENTS_EMPTY
E_UNAUTHENTICATED
401: no or unusableAuthorization, unknown user or wrong password - one code for all of them.- See Also:
E_FORBIDDEN
403: authenticated, but no group grants the operation's privilege.- See Also:
E_SECURE_PORT_REQUIRED
403: production server, request not on a secure port.- See Also:
E_UNKNOWN_OPERATION
E_UNKNOWN_APPLICATION
404:app_idnames an application this server has not loaded.- See Also:
E_METHOD_NOT_ALLOWED
E_NOT_CONFIGURED
409: the application is loaded but no transport can be offered for it.- See Also:
E_STORE_FAILURE
E_INTERNAL
ERRORS
HEADER_DEVICE
The device UUID header, required on device operations only (section 1.1).- See Also:
HEADER_FETCH_MODE
The Fetch Metadata header a Browser sets on a fetch, an XHR and a navigation to a potentially trustworthy origin (https, the loopback) and no page script can set or remove: a request carrying it is a Browser's, and its 401 carries no challenge (section 1.3).- See Also:
HEADER_ORIGIN
The header a Browser sets on every request that is not a GET or a HEAD, over plain http to any address too, and no page script can set or remove: a request carrying it is a Browser's, and its 401 carries no challenge (section 1.3).- See Also:
WWW_AUTHENTICATE
The challenge a 401 carries (RFC 7617 section 2.1), except to a Browser's request (HEADER_FETCH_MODEorHEADER_ORIGIN, section 1.3).- See Also:
CACHE_CONTROL
TRANSPORT_VAPID
TRANSPORT_FCM
URGENCY_HIGH
URGENCY_NORMAL
URGENCY_LOW
BROADCAST
Therecipientsentry that is the broadcast (section 5.6, Ruling 3).- See Also:
DATA_IIZI
The reserved key ofdatathe server writes (section 6.2).- See Also:
IIZI_MESSAGE
The members ofdata.iizi: the message ID, the application, the Topic, when it was sent and the push server ID, on both legs; and on the FCM leg only, the section 6.1 object as the caller gave it, without itsdata(ruling of 2026-09-22, CC-PUSH-FCM-MAP finding 2: members mapped to native FCM fields never reach the device's JavaScript, so the content travels once more underdata.iizi; ruling of 2026-09-23, CC-PUSH-P3 RR-11: added byFcmTransport.buildMessageand not atpush, so that the Web Push leg, whose Service Worker decrypts the whole object, keeps its size for the caller).IIZI_SERVERsince O-4a (CC-DESIGN-PUSH-APPID-FILTER SV-2): the subscription store the message was sent from, the same for every server sharing it.- See Also:
IIZI_APP_ID
The members ofdata.iizi: the message ID, the application, the Topic, when it was sent and the push server ID, on both legs; and on the FCM leg only, the section 6.1 object as the caller gave it, without itsdata(ruling of 2026-09-22, CC-PUSH-FCM-MAP finding 2: members mapped to native FCM fields never reach the device's JavaScript, so the content travels once more underdata.iizi; ruling of 2026-09-23, CC-PUSH-P3 RR-11: added byFcmTransport.buildMessageand not atpush, so that the Web Push leg, whose Service Worker decrypts the whole object, keeps its size for the caller).IIZI_SERVERsince O-4a (CC-DESIGN-PUSH-APPID-FILTER SV-2): the subscription store the message was sent from, the same for every server sharing it.- See Also:
IIZI_TOPIC
The members ofdata.iizi: the message ID, the application, the Topic, when it was sent and the push server ID, on both legs; and on the FCM leg only, the section 6.1 object as the caller gave it, without itsdata(ruling of 2026-09-22, CC-PUSH-FCM-MAP finding 2: members mapped to native FCM fields never reach the device's JavaScript, so the content travels once more underdata.iizi; ruling of 2026-09-23, CC-PUSH-P3 RR-11: added byFcmTransport.buildMessageand not atpush, so that the Web Push leg, whose Service Worker decrypts the whole object, keeps its size for the caller).IIZI_SERVERsince O-4a (CC-DESIGN-PUSH-APPID-FILTER SV-2): the subscription store the message was sent from, the same for every server sharing it.- See Also:
IIZI_SENT
The members ofdata.iizi: the message ID, the application, the Topic, when it was sent and the push server ID, on both legs; and on the FCM leg only, the section 6.1 object as the caller gave it, without itsdata(ruling of 2026-09-22, CC-PUSH-FCM-MAP finding 2: members mapped to native FCM fields never reach the device's JavaScript, so the content travels once more underdata.iizi; ruling of 2026-09-23, CC-PUSH-P3 RR-11: added byFcmTransport.buildMessageand not atpush, so that the Web Push leg, whose Service Worker decrypts the whole object, keeps its size for the caller).IIZI_SERVERsince O-4a (CC-DESIGN-PUSH-APPID-FILTER SV-2): the subscription store the message was sent from, the same for every server sharing it.- See Also:
IIZI_SERVER
The members ofdata.iizi: the message ID, the application, the Topic, when it was sent and the push server ID, on both legs; and on the FCM leg only, the section 6.1 object as the caller gave it, without itsdata(ruling of 2026-09-22, CC-PUSH-FCM-MAP finding 2: members mapped to native FCM fields never reach the device's JavaScript, so the content travels once more underdata.iizi; ruling of 2026-09-23, CC-PUSH-P3 RR-11: added byFcmTransport.buildMessageand not atpush, so that the Web Push leg, whose Service Worker decrypts the whole object, keeps its size for the caller).IIZI_SERVERsince O-4a (CC-DESIGN-PUSH-APPID-FILTER SV-2): the subscription store the message was sent from, the same for every server sharing it.- See Also:
IIZI_NOTIFICATION
The members ofdata.iizi: the message ID, the application, the Topic, when it was sent and the push server ID, on both legs; and on the FCM leg only, the section 6.1 object as the caller gave it, without itsdata(ruling of 2026-09-22, CC-PUSH-FCM-MAP finding 2: members mapped to native FCM fields never reach the device's JavaScript, so the content travels once more underdata.iizi; ruling of 2026-09-23, CC-PUSH-P3 RR-11: added byFcmTransport.buildMessageand not atpush, so that the Web Push leg, whose Service Worker decrypts the whole object, keeps its size for the caller).IIZI_SERVERsince O-4a (CC-DESIGN-PUSH-APPID-FILTER SV-2): the subscription store the message was sent from, the same for every server sharing it.- See Also:
LIST_LIMIT_DEFAULT
public static final int LIST_LIMIT_DEFAULTThe defaultlimitoflist, and its ceiling.- See Also:
LIST_LIMIT_MAX
public static final int LIST_LIMIT_MAXThe defaultlimitoflist, and its ceiling.- See Also:
Method Details
iiziMembers
public static JSONObject iiziMembers(String messageId, String app, String topic, long sent, String server) Builds the server'sdata.iiziof a send (section 6.2): the ONE place its members are written, called by both writers -PushHttpHandler'spushand the Java API'sPushSendSupport.message- so that the two cannot drift apart (CC-DESIGN-PUSH-APPID-FILTER SV-2). The FCM leg's copy of the notification isFcmTransport.buildMessage's own, added to what this returns.- Parameters:
messageId- The message ID, a UUID.app- The canonical application ID,*for the server itself.topic- The Topic, empty for the application level.sent- When it is sent, epoch milliseconds.server- The push server ID (PushEngine.getServerId()); null only for an engine that was never started, in which case the member is left out, as a server built before O-4a leaves it out.- Returns:
- A new object with the members.
requestMembers
Gets the request members an operation reads. A member outside this set is ignored, so the set is what the client may send and the agreement test checks it against.- Parameters:
operation- One ofOPERATIONS.- Returns:
- The members, never null.
replyMembers
Gets the members of an operation's success reply,okincluded. Optional members (keys: each transport's member is present only when configured) are included.- Parameters:
operation- One ofOPERATIONS.- Returns:
- The members, never null.
entryMembers
isDeviceOperation
Tells whether an operation is a device operation:X-iizirequired and a database user required (section 5.0).- Parameters:
operation- One ofOPERATIONS.- Returns:
- true for
subscribe,unsubscribe,resetandsubscriptions.