RFC 3342
The Application Exchange (APEX) Option Party Pack, Part Deux!
RFC 3342: The Application Exchange (APEX) Option Party Pack, Part Deux! 💖
- Stream: Network Working Group 🌸
- RFC number: 3342 ✨
- Category: Standards Track 👑
- Date: July 2002 🍓
- Authors: G. Klyne (Clearswift Corporation), M. Rose (Dover Beach Consulting, Inc.), M. Schwartz (Code On The Road, LLC), E. Dixon, H. Franklin, J. Kint, D. New, S. Pead 🫶
- Obsoletes / Updates: the header doesn't list any RFCs this one obsoletes or updates 🧚
Status of this Memo ✨
okay so this doc is a standards track protocol spec for the Internet community, and it's basically asking everyone to talk about it and suggest improvements 🗣️💅 If you want to know where this protocol sits in terms of standardization, check the current "Internet Official Protocol Standards" list (that's STD 1) 📜 And yes, you're allowed to distribute this memo as much as you want, no limits 🦋
Copyright Notice 🌈
Copyright (C) The Internet Society (2002). All Rights Reserved. 💜
Abstract 🌸
ngl, the core of APEX is a best-effort, application-layer datagram service 📦 Options are how you change what the core service does, and this memo is where a bunch of those options live. They're all about tweaking the default behavior of APEX's "relaying mesh" 🕸️✨
Table of Contents 🎀
1. The attachOverride Option . . . . . . . . . . . . . . . . . 2
2. The dataTiming Option . . . . . . . . . . . . . . . . . . . 3
2.1 Upper-Bounds on Delivery . . . . . . . . . . . . . . . . . . 4
2.1.1 Final Hop Report . . . . . . . . . . . . . . . . . . . . . . 5
2.1.2 Timing Error Report . . . . . . . . . . . . . . . . . . . . 7
2.2 Reporting on Delayed Delivery . . . . . . . . . . . . . . . 8
2.2.1 Transient Timing Report . . . . . . . . . . . . . . . . . . 9
3. The hold4Endpoint Option . . . . . . . . . . . . . . . . . . 10
4. The dataHopping Option . . . . . . . . . . . . . . . . . . . 13
5. Initial Registrations . . . . . . . . . . . . . . . . . . . 15
5.1 Registration: The attachOverride Option . . . . . . . . . . 15
5.2 Registration: The dataTiming Option . . . . . . . . . . . . 16
5.3 Registration: The hold4Endpoint Option . . . . . . . . . . . 16
5.4 Registration: The dataHopping Option . . . . . . . . . . . . 16
6. The APEX Party Pack DTD . . . . . . . . . . . . . . . . . . 17
7. Security Considerations . . . . . . . . . . . . . . . . . . 18
References . . . . . . . . . . . . . . . . . . . . . . . . . 18
A. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19
B. IANA Considerations . . . . . . . . . . . . . . . . . . . . 19
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 20
Full Copyright Statement . . . . . . . . . . . . . . . . . . 221. The attachOverride Option 🦋
okay bestie, Section 5.1 is where the APEX option registration for attachOverride lives 📋
by default, the relaying mesh lets at most one application attach to a particular endpoint, and it's strictly "first come, first served" 🙅♀️ The attachOverride option is the main character move: it gives priority to whichever application is trying to attach right now 👑
if this option shows up in an attach operation (c.f., Section 4.4.1 of [1]) and some application is already attached to that endpoint, the old attachment gets terminated (c.f., Section 4.4.3 of [1]) at the same time as the new attach is processed 💀 The code attribute on that resulting terminate operation gets set to 556 🔥
heads up, though: any data the old app was waiting for might get delivered to the last app that successfully attached instead 🙈 So apps should take care to handle incoming data with transaction-identifiers they don't recognize (c.f., Section 6.1.1 of [1]) 🫶
this option basically means a new attachment automatically kicks out any existing attachment on the same endpoint ✨ It's super handy when a new attachment is needed from a different device while the old device is still attached 📱💻 Here's the vibe:
+-------+ +-------+
| | -- attach -----> | |
| appl. | | relay |
| #1 | <--------- ok -- | |
+-------+ +-------+
C: <attach endpoint='fred@example.com' transID='1' />
S: <ok />
... some time later appl #2 starts on a different computer ...
+-------+ +-------+
| | <----- attach -- | |
+-------+ | | | appl. |
| | <-- terminate -- | relay | -- ok ---------> | #2 |
| appl. | | | +-------+
| #1 | -- ok ---------> | |
+-------+ +-------+
C: <attach endpoint='fred@example.com' transID='2'>
<option internal='attachOverride' transID='3' />
</attach>
S: <ok />
C: <terminate transID='1' code='556'>overriden</terminate>
S: <ok />2. The dataTiming Option ⏰
Section 5.2 has the APEX option registration for the dataTiming option 📝 This option contains a dataTiming element (c.f., Section 6) ✨
the default APEX relaying mesh is "immediate, best effort" 🏃♀️💨 It assumes every relay and endpoint can process and transfer data with zero delay. So, without any processing options, if a relay is unavailable, the data just gets silently dropped 😭 The dataTiming option is the glow-up here: it adds controlled queuing delays while still giving the originator reasonably predictable behavior 💅
there are two kinds of delay that dataTiming deals with:
- delays in transit through the relaying mesh, maybe from shaky or slow connections, or congested relays 🐢; and,
- delays because the intended endpoint isn't available to receive the data, when it's paired with the
hold4Endpointoption (Section 3) 🫠
so with dataTiming, you can:
- have data discarded if it isn't delivered within a finite amount of time, set with the
noLaterThanattribute (Section 2.1) 🗑️; - have a
statusResponsemessage (c.f., Section 5.1 of [1]) generated if data isn't delivered within a known amount of time, set with thereportAfterattribute (Section 2.2) ⏱️; and, - set an upper limit on how long the
statusResponsemessage can take to arrive, using thereturnTripattribute (Section 2.1.1). After that, the sender can assume the message got lost 👻
This option has zero say over the priority of the data, and it doesn't touch any other part of the relaying process. It's a one-job option, bestie 💅
also, because this option is processed on a per-hop basis, the originator must set the targetHop attribute to the value all and the mustUnderstand attribute to the value true 🔐
2.1. Upper-Bounds on Delivery ⏳
the noLaterThan attribute of the dataTiming option is how you keep delays under control, whether they happen in transit through the relaying mesh or on the way to the recipient endpoint 🎯
if this option shows up in the data operation (c.f., Section 4.4.4 of [1]) and the noLaterThan attribute's value is non-zero, here's what happens:
- For Step 5.2 of Section 4.4.4.1 of [1]:
- right before the data gets sent to the next relay, the
noLaterThanvalue gets adjusted to account for how long the local relay spent processing the data 🧮 (think: time to figure out the next relay, time to successfully issue abindoperation, and then getting ready to immediately issue adataoperation). - if the
noLaterThanvalue drops to less than or equal to zero, something went wrong in processing 🚨 The data element isn't sent to the next relay, and if thereportErrorsattribute is true, the APEX report service gets invoked to send a timing error report.
- right before the data gets sent to the next relay, the
- For Step 5.3 of Section 4.4.4.1 of [1]:
- if the relay doesn't get an
okelement back from the recipient endpoint within the number of milli-seconds given by thenoLaterThanattribute, an error in processing has happened. If thereportErrorsattribute is true, the APEX report service gets invoked to send a timing error report 😱 - otherwise, if the data is successfully transmitted to the recipient and the
returnTripattribute is non-zero, the APEX report service gets invoked to send a final hop report 🎉
- if the relay doesn't get an
one more tea ☕: in some cases, a relay can predict this outcome without actually connecting to the next relay. If it can, it may send a timing error report without connecting to the next relay at all 🔮
2.1.1 Final Hop Report
okay so the APEX report service (c.f., Section 6.2 of [1]) is the one that sends a final hop report 📬 when it gets invoked, and it sends a data operation with:
- its originator identifying the report service associated with the issuing relay
- its recipient identifying the endpoint address of the originator associated with the "dataTiming" option
- a new "dataTiming" option having:
- its "noLaterThan" attribute equal to the "returnTrip" attribute of the original "dataTiming" option
- and no other attributes present
- its content consisting of a "statusResponse" element having:
- its "transID" attribute equal to the "transID" attribute of the "dataTiming" option
- and identifying the original recipient with a permanent success indicator
here's what it looks like 🦋
+-------+ +-------+
| | -- data -------> | |
| relay | | appl. |
| | <--------- ok -- | #2 |
+-------+ +-------+
C: <data content='cid:1@example.com'>
<originator identity='fred@example.com' />
<recipient identity='barney@example.com' />
<option internal='dataTiming' targetHop='all'
mustUnderstand='true' transID='86'>
<dataTiming noLaterThan='10000' returnTrip='20000' />
</option>
</data>
S: <ok />
+-------+ +-------+
| | <------- data -- | |
| appl. | | relay |
| #1 | -- ok ---------> | |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='apex=report@example.com' />
<recipient identity='fred@example.com' />
<option internal='dataTiming' targetHop='all'
mustUnderstand='true' transID='99'>
<dataTiming noLaterThan='20000' />
</option>
<data-content Name='Content'>
<statusResponse transID='86'>
<destination identity='barney@example.com'>
<reply code='250' />
</destination>
</statusResponse>
</data-content>
</data>
S: <ok />2.1.2 Timing Error Report
when the APEX report service (c.f., Section 6.2 of [1]) gets invoked to send a timing error report 🚨, it issues a data operation with:
- its originator identifying the report service associated with the issuing relay
- its recipient identifying the endpoint address of the originator associated with the "dataTiming" option
- its content consisting of a "statusResponse" element having:
- its "transID" attribute equal to the "transID" attribute of the "dataTiming" option
- and identifying the original recipient with a permanent failure indicator
example time 💅
+-------+ +-------+
| | -- data -------> | |
| appl. | | relay |
| | <--------- ok -- | |
+-------+ +-------+
C: <data content='cid:1@example.com'>
<originator identity='fred@example.com' />
<recipient identity='barney@example.com' />
<option internal='dataTiming' targetHop='all'
mustUnderstand='true' transID='86'>
<dataTiming noLaterThan='6000' reportErrors='true' />
</option>
</data>
S: <ok />
... some time later ...
+-------+ +-------+
| | <------- data -- | |
| appl. | | relay |
| | -- ok ---------> | |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='apex=report@example.com' />
<recipient identity='fred@example.com' />
<data-content Name='Content'>
<statusResponse transID='86'>
<destination identity='barney@example.com'>
<reply code='550' />
</destination>
</statusResponse>
</data-content>
</data>
S: <ok />2.2. Reporting on Delayed Delivery
ok this one's about telling the originator when delivery is running late 🐢. The "reportAfter" attribute of the "dataTiming" option lets the originator get notified if delivery is delayed beyond a specified time. the data itself isn't affected, it still gets delivered 🫶. also, if "noLaterThan" is non-zero, it gives the operational upper-bounds for "reportAfter", so keep that in mind.
if this option is present in the "data" operation (c.f., Section 4.4.4 of [1]) and the value of "reportAfter" is non-zero, then:
- For Step 5.2 of Section 4.4.4.1 of [1]:
- Immediately prior to sending the data to the next relay, the value of the "reportAfter" attribute is adjusted to reflect the processing time of the data at the local relay (e.g., the time required to determine the next relay, to successfully issue a "bind" operation, and then be ready to immediately issue a "data" operation).
- If the value of the "reportAfter" attribute becomes less than or equal to zero, then its value is set to zero and the APEX report service is invoked to send a transient timing report; regardless, the data element is sent to the next relay.
- For Step 5.3 of Section 4.4.4.1 of [1]:
- If the relay does not receive an "ok" element from the recipient endpoint within the number of milli-seconds indicated by the value of the "reportAfter" attribute, then its value is set to zero and the APEX report service is invoked to send a transient timing report.
2.2.1 Transient Timing Report
when the APEX report service (c.f., Section 6.2 of [1]) is invoked to send a transient timing report ⏳, it issues a data operation with:
- its originator identifying the report service associated with the issuing relay
- its recipient identifying the endpoint address of the originator associated with the "dataTiming" option
- its content consisting of a "statusResponse" element having:
- its "transID" attribute equal to the "transID" attribute of the "dataTiming" option
- and identifying the original recipient with a transient success indicator
the vibe check 🌸
+-------+ +-------+
| | -- data -------> | |
| appl. | | relay |
| #1 | <--------- ok -- | |
+-------+ +-------+
C: <data content='cid:1@example.com'>
<originator identity='fred@example.com' />
<recipient identity='barney@example.com' />
<option internal='dataTiming' targetHop='all'
mustUnderstand='true' transID='86'>
<dataTiming reportAfter='60000' />
</option>
</data>
S: <ok />
... some time later ...
+-------+ +-------+
| | <------- data -- | |
| relay | | relay |
| #n-1 | -- ok ---------> | #n |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='apex=report@example.com' />
<recipient identity='fred@example.com' />
<data-content Name='Content'>
<statusResponse transID='86'>
<destination identity='barney@example.com'>
<reply code='350' />
</destination>
</statusResponse>
</data-content>
</data>
S: <ok />3. The hold4Endpoint Option ✨
Section 5.3 has the APEX option registration for the "hold4Endpoint" option 📋.
so the default vibe of the APEX relaying mesh, when there are no processing options 🙃, is to silently drop data for a recipient if its endpoint isn't attached. the "hold4Endpoint" option is the fix: it lets data get queued if the recipient endpoint isn't attached 🧚.
if this option is present in the "data" operation (c.f., Section 4.4.4 of [1]), and the value of the "hold4Endpoint" attribute is true, then:
- For Step 5.3 of Section 4.4.4.1 of [1]:
- If the recipient's endpoint is not currently attached, the relay will queue the data waiting for an application to attach as that endpoint.
heads up 👀: if there's no upper-bounds on delivery, like the limits the dataTiming option gives (Section 2), the data will be queued indefinitely for the endpoint.
example 🍓
+-------+ +-------+
| | -- data -------> | |
| appl. | | relay |
| #1 | <--------- ok -- | |
+-------+ +-------+
C: <data content='cid:1@example.com'>
<originator identity='fred@example.com' />
<recipient identity='barney@example.com' />
<option internal='hold4Endpoint' />
<option internal='dataTiming' targetHop='all'
mustUnderstand='true' transID='86'>
<dataTiming noLaterThan='60000' />
</option>
</data>
S: <ok />
... some time later the recipient's endpoint attaches ...
+-------+ +-------+
| | <----- attach -- | |
| | | |
| | -- ok ---------> | |
| relay | | appl. |
| | -- data -------> | #2 |
| | | |
| | <--------- ok -- | |
+-------+ +-------+
C: <attach endpoint='barney@example.com' transID='2'>
<option internal='attachOverride' transID='3' />
</attach>
S: <ok />
C: <data content='cid:1@example.com'>
<originator identity='fred@example.com' />
<recipient identity='barney@example.com' />
<option internal='hold4Endpoint' />
<option internal='dataTiming' targetHop='all'
mustUnderstand='true' transID='86'>
<dataTiming noLaterThan='18000' />
</option>
</data>
S: <ok />4. The dataHopping Option ✨
okay so, to catch misconfigurations that cause forwarding loops in the APEX relaying mesh 🌀, the APEX pubsub service brings back something lowkey like the IP TTL [2] mechanism, but as an APEX option. it's giving main character energy 💅 The registration for the "dataHopping" option is in Section 5.4.
if this option is in the "data" operation (c.f., Section 4.4.4 of [1]) and the noMoreThan attribute is non-zero, then:
- For Step 5.2 of Section 4.4.4.1 of [1]:
Right before the data gets sent to the next relay, the value of the noMoreThan attribute goes down by 1 ⬇️
If the value of noMoreThan ends up less than or equal to zero, something went wrong in processing 😭. The data element doesn't get sent to the next relay, and if reportErrors is true, the APEX report service gets invoked to send an error report.
one more thing, bestie 🫶: this option gets processed on every hop, so the originator has to set targetHop to all and mustUnderstand to true. no skipping this part!
if the APEX report service (c.f., Section 6.2 of [1]) gets invoked to send an error report, it sends a data operation with:
- its originator identifying the report service associated with the issuing relay
- its recipient identifying the endpoint address of the originator associated with the "dataHopping" option
- its content being a
statusResponseelement that has:- its
transIDattribute equal to thetransIDattribute of the "dataHopping" option - and identifies the original recipient with a permanent failure indicator 💀
- its
here's how it plays out 🦋:
+-------+ +-------+
| | -- data -------> | |
| appl. | | relay |
| | <--------- ok -- | #1 |
+-------+ +-------+
C: <data content='cid:1@example.com'>
<originator identity='appl=pubsub/topic=fred@example.com' />
<recipient identity='barney@example.com' />
<option internal='dataHopping' targetHop='all'
mustUnderstand='true' transID='86'>
<dataHopping noMoreThan='2' reportErrors='true' />
</option>
</data>
S: <ok /> +-------+ +-------+
| | -- data -------> | |
| relay | | relay |
| #1 | <--------- ok -- | #2 |
+-------+ +-------+
C: <data content='cid:1@example.com'>
<originator identity='appl=pubsub/topic=fred@example.com' />
<recipient identity='barney@example.com' />
<option internal='dataHopping' targetHop='all'
mustUnderstand='true' transID='86'>
<dataHopping noMoreThan='1' reportErrors='true' />
</option>
</data>
S: <ok />relay #2 decides that more relaying is needed 🤔:
+-------+ +-------+
| | <------- data -- | |
| relay | | relay |
| #1 | -- ok ---------> | #2 |
+-------+ +-------+
C: <data content='#Content'>
<originator identity='apex=report@example.com' />
<recipient identity='appl=pubsub/topic=fred@example.com' />
<data-content Name='Content'>
<statusResponse transID='86'>
<destination identity='barney@example.com'>
<reply code='550' />
</destination>
</statusResponse>
</data-content>
</data>
S: <ok />5. Initial Registrations 🎀
the APEX option registration template is defined in Section 7.1 of [1]. easy peasy 🌸
5.1 Registration: The attachOverride Option 💖
- Option Identification:
attachOverride - Present in: APEX's "attach" element
- Contains: nothing
- Processing Rules: c.f., Section 1
- Contact Information: c.f., the "Authors' Addresses" section of this memo
5.2 Registration: The dataTiming Option ⏰
- Option Identification:
dataTiming - Present in: APEX's "data" element
- Contains: dataTiming (c.f., Section 6)
- Processing Rules: c.f., Section 2
- Contact Information: c.f., the "Authors' Addresses" section of this memo
5.3 Registration: The hold4Endpoint Option 🍓
- Option Identification:
hold4Endpoint - Present in: APEX's "data" element
- Contains: nothing
- Processing Rules: c.f., Section 3
- Contact Information: c.f., the "Authors' Addresses" section of this memo
5.4 Registration: The dataHopping Option 🧚
- Option Identification:
dataHopping - Present in: APEX's "data" element
- Contains: dataHopping (c.f., Section 6)
- Processing Rules: c.f., Section 4
- Contact Information: c.f., the "Authors' Addresses" section of this memo
6. The APEX Party Pack DTD 🧚
this is the DTD for the APEX option party pack, as of 2001-05-14 🎉 (you'll want to refer to it exactly like the comment says, so don't skip that bit 👀)
<!--
DTD for the APEX option party pack, as of 2001-05-14
Refer to this DTD as:
<!ENTITY % APEXPARTY PUBLIC "-//IETF//DTD APEX PARTY//EN" "">
%APEXPARTY;
-->
<!ENTITY % APEXCORE PUBLIC "-//IETF//DTD APEX CORE//EN"
%APEXCORE;
<!--
DTD data types:
entity syntax/reference example
====== ================ =======
hopcount
HOPS 0..255 17
milli-seconds
MILLISECS 0..2147483647 60000
-->
<!ENTITY % HOPS "CDATA">
<!ENTITY % MILLISECS
"CDATA">
<!ELEMENT dataHopping EMPTY>
<!ATTLIST dataHopping
noMoreThan %HOPS; "0"
reportErrors
(true|false) "false">
<!ELEMENT dataTiming EMPTY>
<!ATTLIST dataTiming
noLaterThan %MILLISECS; "0"
returnTrip %MILLISECS; "0"
reportAfter %MILLISECS; "0"
reportErrors
(true|false) "false">7. Security Considerations 🙈
okay this part is seriously important, so pay attention bestie 😭. for the big security stuff, go check Section 11 of [1]. that's the main source of truth ✨
and then there's the extra drama 👇
- the dataTiming option (Section 2) can be used to expose private network topology 👀. so an administrator might want to turn this option off except at the ingress/egress points for its administrative domain. protect the vibes 🛡️
- the hold4Endpoint option (Section 3) can be used to help with denial-of-service attacks 🚨. so an administrator might want to put administrative limits on this attribute (for example, always making sure the "dataTiming" option is also present with a short-lived
noLaterThanattribute). keep it tight, no cap 🫶
References 📚
[1] Rose, M., Klyne, G. and D. Crocker, "The Application Exchange Core", RFC 3340, July 2002.
[2] Postel, J., "Internet Protocol", STD 5, RFC 791, September 1981.
[3] Newman, D., "Deliver By SMTP Service Extension", RFC 2852, June 2000.
Appendix A. Acknowledgements 💜
the authors gave a huge shoutout to Chris Newman and Bob Wyman 🙌. also, the dataTiming option is kinda like the "Deliver By" SMTP service extension that Dan Newman wrote up in [3]. iykyk 🦋
Appendix B. IANA Considerations 🌈
IANA finished the registrations listed in Section 5. ✅
Authors' Addresses 🫶
Graham Klyne
Clearswift Corporation
1310 Waterside
Arlington Business Park
Theale, Reading RG7 4SA
UK
Phone: +44 11 8903 8903
EMail: Graham.Klyne@MIMEsweeper.com
Marshall T. Rose
Dover Beach Consulting, Inc.
POB 255268
Sacramento, CA 95865-5268
US
Phone: +1 916 483 8878
EMail: mrose@dbc.mtview.ca.us
Michael F. Schwartz
Code On The Road, LLC
EMail: schwartz@CodeOnTheRoad.com
URI: http://www.CodeOnTheRoad.com
Eric Dixon
EMail: edixon@myrealbox.com
Huston Franklin
EMail: huston@franklin.ro
Jay Kint
EMail: d20@icosahedron.org
Darren New
5390 Caminito Exquisito
San Diego, CA 92130
US
Phone: +1 858 350 9733
EMail: dnew@san.rr.com
Scott Pead
EMail: spead@fiber.netFull Copyright Statement 📜
Copyright (C) The Internet Society (2002). All Rights Reserved. 💖
okay so this bit is the legal stuff, and it matters. you're allowed to copy and share this document, and to make derivative works that comment on or explain it or help with implementing it, as long as the copyright notice and this paragraph are on every copy and derivative work 📄. you can translate it into languages other than English too 🌍. BUT the document itself can't be modified in any way (like taking off the copyright notice or the references to the Internet Society or other Internet organizations). the one exception is for developing Internet standards, where you follow the copyright procedures in the Internet Standards process 🔥.
these permissions are perpetual and won't be revoked by the Internet Society or its successors or assigns ♾️.
this document and the info in it is provided on an "AS IS" basis. THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE 💅.
Acknowledgement 💜
funding for the RFC Editor function is currently provided by the Internet Society ✨
📦 where this page comes from
- ietf: rfc3342 2002-07
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms