From c1723501666031fbcca91e01d831cf6af8c6d191 Mon Sep 17 00:00:00 2001 From: VasilevNStas Date: Sun, 28 Jun 2026 19:42:02 +0300 Subject: [PATCH] docs(pong): document zero-value contract for Property.ends, Peer.expires, Pong.expires Lease.ends already documents that 0 means free tier, but the three sibling timestamp fields shared the same uint64 type without a zero-value contract. A client evaluating expires < now would see 0 < now == true for any unpopulated field and treat a perfectly live Node/Peer/slot as permanently expired/deleted. Add 'Zero means ...' to each field comment so implementers know the sentinel is safe to test for. --- pong.proto | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/pong.proto b/pong.proto index 7606fa2..9b18d0f 100644 --- a/pong.proto +++ b/pong.proto @@ -23,7 +23,8 @@ message Lease { message Property { // Unix timestamp (seconds) at which the slot itself expires — // i.e. when the customer's purchase runs out. Independent of the - // life of the underlying Node (see `expires`). + // life of the underlying Node (see `expires`). Zero means no + // purchase record is available (e.g. not yet loaded from Hub). uint64 ends = 1; // ISO 3166-1 alpha-2 country code of the slot ("US", "DE", …). @@ -84,7 +85,8 @@ message Peer { uint64 metered = 4; // Unix timestamp (seconds) at which the peer is scheduled for - // decommission. + // decommission. Zero means no decommission is scheduled; the + // client MUST NOT treat a zero as "already expired". uint64 expires = 5; // TLS Server Name Indication the peer presents on its endpoint. @@ -130,7 +132,8 @@ message Pong { // the authoritative source for the connected Node's retirement; // when a Property slot is backed by the same Node, the client // MUST prefer Pong.expires over Property.expires if the two - // disagree. + // disagree. Zero means no decommission is scheduled; the client + // MUST NOT treat a zero as "already expired". uint64 expires = 14; // Fixed Unix timestamp (seconds) at which the client's free-tier