transport cleanup

Author: zekageri

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+### Changed
+- Breaking: renamed the public transport struct from `Subscription` to `WebPushSubscription` everywhere with no compatibility alias.
+- Breaking: renamed `PushMessage.sub` to `PushMessage.subscription` for API consistency.
+- Breaking: removed app-level metadata fields `deviceId`, `disabledTags`, and `deleted` from the transport struct.
+- `validateSubscription()` now validates only the required Web Push transport fields: `endpoint`, `p256dh`, and `auth`.
+
 ## [2.0.0] - 2026-03-28
 
 ### Added

README.md

@@ -53,13 +53,13 @@ void loop() {}
 
 ## Usage
 
-### Subscription / Structured Payload
+### WebPushSubscription / Structured Payload
 
 ```cpp
-Subscription sub;
-sub.endpoint = "https://fcm.googleapis.com/fcm/send/...";
-sub.p256dh = "BME...";
-sub.auth = "nsa...";
+WebPushSubscription subscription;
+subscription.endpoint = "https://fcm.googleapis.com/fcm/send/...";
+subscription.p256dh = "BME...";
+subscription.auth = "nsa...";
 
 PushPayload payload;
 payload.title = "Hello";
@@ -71,7 +71,7 @@ payload.icon = "https://example.com/icon.png";
 ### Async Send
 
 ```cpp
-WebPushEnqueueResult enqueue = webPush.send(sub, payload, [](WebPushResult result) {
+WebPushEnqueueResult enqueue = webPush.send(subscription, payload, [](WebPushResult result) {
     if (!result.ok()) {
         ESP_LOGE("WEBPUSH", "Push failed: %s (status %d)",
                  result.message, result.statusCode);
@@ -95,13 +95,13 @@ doc["title"] = "Hello";
 doc["body"] = "ESP32";
 doc["tag"] = "demo";
 
-WebPushResult result = webPush.send(sub, doc);
+WebPushResult result = webPush.send(subscription, doc);
 ```
 
 ### Sync Send
 
 ```cpp
-WebPushResult result = webPush.send(sub, payload);
+WebPushResult result = webPush.send(subscription, payload);
 if (!result.ok()) {
     ESP_LOGW("WEBPUSH", "Sync push failed: %s", result.message);
 }
@@ -111,7 +111,7 @@ if (!result.ok()) {
 
 ```cpp
 PushMessage msg;
-msg.sub = sub;
+msg.subscription = subscription;
 msg.payload = "{\"title\":\"Hello\",\"body\":\"ESP32\"}";
 
 // Raw payload strings remain supported, but they are not schema-validated.
@@ -156,12 +156,12 @@ if (webPush.isInitialized()) {
 - `bool init(const WebPushVapidConfig&, const WebPushConfig& = {})`
 - `WebPushEnqueueResult send(const PushMessage&, WebPushResultCB cb)`
 - `WebPushResult send(const PushMessage&)`
-- `WebPushEnqueueResult send(const Subscription&, const PushPayload&, WebPushResultCB cb)`
-- `WebPushResult send(const Subscription&, const PushPayload&)`
-- `WebPushEnqueueResult send(const Subscription&, const JsonDocument&, WebPushResultCB cb)`
-- `WebPushResult send(const Subscription&, const JsonDocument&)`
-- `WebPushEnqueueResult send(const Subscription&, JsonVariantConst, WebPushResultCB cb)`
-- `WebPushResult send(const Subscription&, JsonVariantConst)`
+- `WebPushEnqueueResult send(const WebPushSubscription&, const PushPayload&, WebPushResultCB cb)`
+- `WebPushResult send(const WebPushSubscription&, const PushPayload&)`
+- `WebPushEnqueueResult send(const WebPushSubscription&, const JsonDocument&, WebPushResultCB cb)`
+- `WebPushResult send(const WebPushSubscription&, const JsonDocument&)`
+- `WebPushEnqueueResult send(const WebPushSubscription&, JsonVariantConst, WebPushResultCB cb)`
+- `WebPushResult send(const WebPushSubscription&, JsonVariantConst)`
 - `void requestStop()`
 - `WebPushJoinStatus join(uint32_t timeoutMs)`
 - `void setNetworkValidator(WebPushNetworkValidator)`

examples/basic_web_push/basic_web_push.ino

@@ -28,18 +28,18 @@ void setup() {
 
 	webPush.init(vapid, cfg);
 
-	Subscription sub;
-	sub.endpoint = "https://fcm.googleapis.com/fcm/send/...";
-	sub.p256dh = "BMEp256dhBase64Url...";
-	sub.auth = "authSecretBase64Url...";
+	WebPushSubscription subscription;
+	subscription.endpoint = "https://fcm.googleapis.com/fcm/send/...";
+	subscription.p256dh = "BMEp256dhBase64Url...";
+	subscription.auth = "authSecretBase64Url...";
 
 	PushPayload payload;
 	payload.title = "Hello";
 	payload.body = "ESP32";
 	payload.tag = "basic-demo";
 	payload.icon = "https://www.esptoolkit.hu/icon.png";
 
-	WebPushEnqueueResult enqueue = webPush.send(sub, payload, [](WebPushResult result) {
+	WebPushEnqueueResult enqueue = webPush.send(subscription, payload, [](WebPushResult result) {
 		if (!result.ok()) {
 			Serial.printf(
 			    "[webpush] async failed: %s (status %d)\n",
@@ -63,7 +63,7 @@ void setup() {
 	jsonPayload["body"] = "ESP32";
 	jsonPayload["tag"] = "basic-demo";
 
-	WebPushResult syncResult = webPush.send(sub, jsonPayload);
+	WebPushResult syncResult = webPush.send(subscription, jsonPayload);
 	if (!syncResult.ok()) {
 		Serial.printf(
 		    "[webpush] sync failed: %s\n",

src/esp_webPush/webPush.cpp

@@ -237,17 +237,19 @@ WebPushResult ESPWebPush::send(const PushMessage &msg) {
 }
 
 WebPushEnqueueResult ESPWebPush::send(
-    const Subscription &sub, const PushPayload &payload, WebPushResultCB callback
+    const WebPushSubscription &subscription, const PushPayload &payload, WebPushResultCB callback
 ) {
 	PushMessage message;
 	WebPushResult result{};
-	if (!buildMessage(sub, payload, message, result)) {
+	if (!buildMessage(subscription, payload, message, result)) {
 		return enqueueResultForError(result.error);
 	}
 	return send(message, std::move(callback));
 }
 
-WebPushResult ESPWebPush::send(const Subscription &sub, const PushPayload &payload) {
+WebPushResult ESPWebPush::send(
+    const WebPushSubscription &subscription, const PushPayload &payload
+) {
 	if (_stopRequested.load(std::memory_order_acquire)) {
 		return resultForError(WebPushError::ShuttingDown);
 	}
@@ -257,34 +259,38 @@ WebPushResult ESPWebPush::send(const Subscription &sub, const PushPayload &paylo
 
 	PushMessage message;
 	WebPushResult result{};
-	if (!buildMessage(sub, payload, message, result)) {
+	if (!buildMessage(subscription, payload, message, result)) {
 		return result;
 	}
 	return send(message);
 }
 
 WebPushEnqueueResult ESPWebPush::send(
-    const Subscription &sub, const JsonDocument &payload, WebPushResultCB callback
+    const WebPushSubscription &subscription, const JsonDocument &payload, WebPushResultCB callback
 ) {
-	return send(sub, payload.as<JsonVariantConst>(), std::move(callback));
+	return send(subscription, payload.as<JsonVariantConst>(), std::move(callback));
 }
 
-WebPushResult ESPWebPush::send(const Subscription &sub, const JsonDocument &payload) {
-	return send(sub, payload.as<JsonVariantConst>());
+WebPushResult ESPWebPush::send(
+    const WebPushSubscription &subscription, const JsonDocument &payload
+) {
+	return send(subscription, payload.as<JsonVariantConst>());
 }
 
 WebPushEnqueueResult ESPWebPush::send(
-    const Subscription &sub, JsonVariantConst payload, WebPushResultCB callback
+    const WebPushSubscription &subscription, JsonVariantConst payload, WebPushResultCB callback
 ) {
 	PushMessage message;
 	WebPushResult result{};
-	if (!buildMessage(sub, payload, message, result)) {
+	if (!buildMessage(subscription, payload, message, result)) {
 		return enqueueResultForError(result.error);
 	}
 	return send(message, std::move(callback));
 }
 
-WebPushResult ESPWebPush::send(const Subscription &sub, JsonVariantConst payload) {
+WebPushResult ESPWebPush::send(
+    const WebPushSubscription &subscription, JsonVariantConst payload
+) {
 	if (_stopRequested.load(std::memory_order_acquire)) {
 		return resultForError(WebPushError::ShuttingDown);
 	}
@@ -294,7 +300,7 @@ WebPushResult ESPWebPush::send(const Subscription &sub, JsonVariantConst payload
 
 	PushMessage message;
 	WebPushResult result{};
-	if (!buildMessage(sub, payload, message, result)) {
+	if (!buildMessage(subscription, payload, message, result)) {
 		return result;
 	}
 	return send(message);
@@ -369,7 +375,10 @@ WebPushResult ESPWebPush::invalidPayloadResult() const {
 }
 
 bool ESPWebPush::buildMessage(
-    const Subscription &sub, const PushPayload &payload, PushMessage &message, WebPushResult &result
+    const WebPushSubscription &subscription,
+    const PushPayload &payload,
+    PushMessage &message,
+    WebPushResult &result
 ) const {
 	std::string serializedPayload;
 	const char *payloadError = serializePushPayload(payload, serializedPayload);
@@ -379,13 +388,16 @@ bool ESPWebPush::buildMessage(
 		return false;
 	}
 
-	message.sub = sub;
+	message.subscription = subscription;
 	message.payload = std::move(serializedPayload);
 	return true;
 }
 
 bool ESPWebPush::buildMessage(
-    const Subscription &sub, JsonVariantConst payload, PushMessage &message, WebPushResult &result
+    const WebPushSubscription &subscription,
+    JsonVariantConst payload,
+    PushMessage &message,
+    WebPushResult &result
 ) const {
 	std::string serializedPayload;
 	const char *payloadError = validateAndSerializePushPayload(payload, serializedPayload);
@@ -395,7 +407,7 @@ bool ESPWebPush::buildMessage(
 		return false;
 	}
 
-	message.sub = sub;
+	message.subscription = subscription;
 	message.payload = std::move(serializedPayload);
 	return true;
 }
@@ -423,22 +435,22 @@ WebPushResult ESPWebPush::handleMessage(const PushMessage &msg) {
 			continue;
 		}
 
-		std::vector<uint8_t> body = encryptPayload(msg.payload, msg.sub);
+		std::vector<uint8_t> body = encryptPayload(msg.payload, msg.subscription);
 		if (body.empty()) {
 			result.error = WebPushError::EncryptFailed;
 			result.message = errorToString(result.error);
 			return result;
 		}
 
-		const std::string aud = endpointOrigin(msg.sub.endpoint);
+		const std::string aud = endpointOrigin(msg.subscription.endpoint);
 		const std::string jwt = jwtForAudience(aud);
 		if (jwt.empty()) {
 			result.error = WebPushError::JwtFailed;
 			result.message = errorToString(result.error);
 			return result;
 		}
 
-		WebPushResult request = sendPushRequest(msg.sub.endpoint, jwt, body);
+		WebPushResult request = sendPushRequest(msg.subscription.endpoint, jwt, body);
 		if (request.ok()) {
 			return request;
 		}
@@ -520,8 +532,10 @@ uint32_t ESPWebPush::calcRetryDelayMs(uint8_t attempt) const {
 	return delay;
 }
 
-bool ESPWebPush::validateSubscription(const Subscription &sub, WebPushResult &result) const {
-	if (sub.deleted || sub.endpoint.empty() || sub.p256dh.empty() || sub.auth.empty()) {
+bool ESPWebPush::validateSubscription(
+    const WebPushSubscription &subscription, WebPushResult &result
+) const {
+	if (subscription.endpoint.empty() || subscription.p256dh.empty() || subscription.auth.empty()) {
 		result.error = WebPushError::InvalidSubscription;
 		result.message = errorToString(result.error);
 		return false;
@@ -539,7 +553,7 @@ bool ESPWebPush::validatePayloadSize(const std::string &payload, WebPushResult &
 }
 
 bool ESPWebPush::validateMessage(const PushMessage &msg, WebPushResult &result) const {
-	if (!validateSubscription(msg.sub, result)) {
+	if (!validateSubscription(msg.subscription, result)) {
 		return false;
 	}
 	return validatePayloadSize(msg.payload, result);

src/esp_webPush/webPush.h

@@ -37,17 +37,14 @@ struct WebPushVapidConfig {
 	std::string privateKeyBase64;
 };
 
-struct Subscription {
+struct WebPushSubscription {
 	std::string endpoint;
 	std::string p256dh;
 	std::string auth;
-	std::string deviceId;
-	std::vector<std::string> disabledTags;
-	bool deleted = false;
 };
 
 struct PushMessage {
-	Subscription sub;
+	WebPushSubscription subscription;
 	std::string payload;
 };
 
@@ -161,17 +158,23 @@ class ESPWebPush {
 	WebPushEnqueueResult send(const PushMessage &msg, WebPushResultCB callback);
 	WebPushResult send(const PushMessage &msg);
 	WebPushEnqueueResult send(
-	    const Subscription &sub, const PushPayload &payload, WebPushResultCB callback
+	    const WebPushSubscription &subscription,
+	    const PushPayload &payload,
+	    WebPushResultCB callback
 	);
-	WebPushResult send(const Subscription &sub, const PushPayload &payload);
+	WebPushResult send(const WebPushSubscription &subscription, const PushPayload &payload);
 	WebPushEnqueueResult send(
-	    const Subscription &sub, const JsonDocument &payload, WebPushResultCB callback
+	    const WebPushSubscription &subscription,
+	    const JsonDocument &payload,
+	    WebPushResultCB callback
 	);
-	WebPushResult send(const Subscription &sub, const JsonDocument &payload);
+	WebPushResult send(const WebPushSubscription &subscription, const JsonDocument &payload);
 	WebPushEnqueueResult send(
-	    const Subscription &sub, JsonVariantConst payload, WebPushResultCB callback
+	    const WebPushSubscription &subscription,
+	    JsonVariantConst payload,
+	    WebPushResultCB callback
 	);
-	WebPushResult send(const Subscription &sub, JsonVariantConst payload);
+	WebPushResult send(const WebPushSubscription &subscription, JsonVariantConst payload);
 
 	void setNetworkValidator(WebPushNetworkValidator validator);
 
@@ -203,19 +206,19 @@ class ESPWebPush {
 	uint32_t calcRetryDelayMs(uint8_t attempt) const;
 	bool waitForStopAwareDelay(uint32_t delayMs) const;
 
-	bool validateSubscription(const Subscription &sub, WebPushResult &result) const;
+	bool validateSubscription(const WebPushSubscription &subscription, WebPushResult &result) const;
 	bool validatePayloadSize(const std::string &payload, WebPushResult &result) const;
 	bool validateMessage(const PushMessage &msg, WebPushResult &result) const;
 	bool validateVapidSubject(WebPushResult &result) const;
 	bool validateVapidKeys(WebPushResult &result);
 	bool buildMessage(
-	    const Subscription &sub,
+	    const WebPushSubscription &subscription,
 	    const PushPayload &payload,
 	    PushMessage &message,
 	    WebPushResult &result
 	) const;
 	bool buildMessage(
-	    const Subscription &sub,
+	    const WebPushSubscription &subscription,
 	    JsonVariantConst payload,
 	    PushMessage &message,
 	    WebPushResult &result
@@ -276,7 +279,7 @@ class ESPWebPush {
 
 	std::vector<uint8_t> encryptPayload(
 	    const std::string &plaintext,
-	    const Subscription &sub
+	    const WebPushSubscription &subscription
 	);
 
 	bool generateSalt(uint8_t *saltBin);

src/esp_webPush/webPush_crypto.cpp

@@ -416,20 +416,22 @@ bool ESPWebPush::buildRecordBody(
 	return true;
 }
 
-std::vector<uint8_t> ESPWebPush::encryptPayload(const std::string &plaintext, const Subscription &sub) {
+std::vector<uint8_t> ESPWebPush::encryptPayload(
+    const std::string &plaintext, const WebPushSubscription &subscription
+) {
 	std::lock_guard<std::mutex> guard(_cryptoMutex);
 	if (!initCrypto()) {
 		return {};
 	}
 
 	std::vector<uint8_t> userPubKey;
-	if (!decodeP256PublicKey(sub.p256dh, userPubKey)) {
+	if (!decodeP256PublicKey(subscription.p256dh, userPubKey)) {
 		ESP_LOGE(kTag, "encryptPayload: client public key invalid");
 		return {};
 	}
 
 	std::vector<uint8_t> authSecret;
-	if (!base64UrlDecode(sub.auth, authSecret) || authSecret.size() != 16) {
+	if (!base64UrlDecode(subscription.auth, authSecret) || authSecret.size() != 16) {
 		ESP_LOGE(kTag, "encryptPayload: auth secret invalid");
 		return {};
 	}