dovecot-2.1-pigeonhole: Improved specification of the vnd.doveco...
pigeonhole at rename-it.nl
pigeonhole at rename-it.nl
Wed Oct 17 22:50:00 EEST 2012
details: http://hg.rename-it.nl/dovecot-2.1-pigeonhole/rev/fd7257cb40ea
changeset: 1664:fd7257cb40ea
user: Stephan Bosch <stephan at rename-it.nl>
date: Wed Oct 17 21:49:55 2012 +0200
description:
Improved specification of the vnd.dovecot.duplicate extension.
diffstat:
doc/rfc/spec-bosch-sieve-duplicate.txt | 132 ++++++++++++++--------------
doc/rfc/xml/reference.INCLUDE.xml | 17 +++
doc/rfc/xml/spec-bosch-sieve-duplicate.xml | 49 +++++++---
3 files changed, 118 insertions(+), 80 deletions(-)
diffs (truncated from 324 to 300 lines):
diff -r 762b6a885897 -r fd7257cb40ea doc/rfc/spec-bosch-sieve-duplicate.txt
--- a/doc/rfc/spec-bosch-sieve-duplicate.txt Wed Oct 17 02:55:07 2012 +0200
+++ b/doc/rfc/spec-bosch-sieve-duplicate.txt Wed Oct 17 21:49:55 2012 +0200
@@ -2,7 +2,7 @@
Pigeonhole Project S. Bosch
- October 16, 2012
+ October 17, 2012
Sieve Email Filtering: Detecting Duplicate Deliveries
@@ -65,9 +65,9 @@
4. Sieve Capability Strings . . . . . . . . . . . . . . . . . . . 5
5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
6. Security Considerations . . . . . . . . . . . . . . . . . . . . 6
- 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6
- 7.1. Normative References . . . . . . . . . . . . . . . . . . . 6
- 7.2. Informative References . . . . . . . . . . . . . . . . . . 6
+ 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
+ 7.1. Normative References . . . . . . . . . . . . . . . . . . . 7
+ 7.2. Informative References . . . . . . . . . . . . . . . . . . 7
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 7
@@ -187,20 +187,50 @@
extension.
The "duplicate" test evaluates to "true" when the provided value was
- seen before. If the value is not known, the test evaluates to
- "false" and the value is added to an internal value tracking list.
+ seen before in an earlier Sieve execution for a previous message
+ delivery. If the value was not seen earlier, the test evaluates to
+ "false".
+
+ As a side-effect, the "duplicate" test adds the evaluated value to an
+ internal duplicate tracking list, so that the test will evaluate to
+ "true" the next time the Sieve script is executed and the same value
+ is encountered. Note that the "duplicate" test MUST only check for
+ duplicates amongst values encountered in previous executions of the
+ Sieve script; it MUST NOT consider values encountered earlier in the
+ current Sieve script execution as potential duplicates. This means
+ that all "duplicate" tests in a Sieve script execution, including
+ those located in scripts included using the "include" [INCLUDE]
+ extension, MUST yield the same result if the arguments are identical.
+
+ Implementations MUST prevent adding values to the internal duplicate
+ tracking list when the Sieve script execution fails. For example,
+ this can be implemented by deferring the definitive modification of
+ the tracking list to the end of the Sieve script execution. If
+ failed script executions would add values to the duplicate tracking
+ list, all "duplicate" tests would erroneously yield "true" for the
+ next delivery attempt of the same message, which can -- depending on
+ the action taken for a duplicate -- easily lead to discarding the
+ message without further notice.
+
Implementations SHOULD limit the number of values (and thereby
messages) that are tracked. Also, implementations SHOULD let entries
- in the value tracking list expire after a short period of time.
+ in the value tracking list expire after a short period of time. The
+ user can explicitly control the length of this expiration time by
+ means of the ":seconds" argument. If the ":seconds" argument is
- The user can explicitly control the length this expiration time by
- means of the ":seconds" argument. If the ":seconds" argument is
+
+
+Bosch [Page 4]
+
+ Sieve: Detecting Duplicate Deliveries October 2012
+
+
omitted, an appropriate default MUST be used. Sites SHOULD impose a
maximum limit on the expiration time. If that limit is exceeded, the
maximum value MUST silently be substituted; exceeding the limit MUST
NOT produce an error.
- By default the tracked value is the content of the message's
+ By default, the tracked value is the content of the message's
Message-ID header field. For more advanced purposes, the content of
another header can be chosen for tracking by specifying the ":header"
argument. The tracked string value can also be specified explicitly
@@ -209,7 +239,8 @@
test command MUST trigger an error at compile time. If the value is
extracted from a header, i.e. when the ":value" argument is not used,
leading and trailing whitespace (see Section 2.2 of RFC 5228 [SIEVE])
- MUST first be trimmed from the value before executing the test.
+ MUST first be trimmed from the value before performing the actual
+ duplicate verification.
Using the ":handle" argument, the duplicate test can be employed for
multiple independent purposes. Only when the tracked value was seen
@@ -217,14 +248,6 @@
same ":handle" argument, it is recognized as a duplicate.
NOTE: The necessary mechanism to track duplicate messages is very
-
-
-
-Bosch [Page 4]
-
- Sieve: Detecting Duplicate Deliveries October 2012
-
-
similar to the mechanism that is needed for tracking duplicate
responses for the "vacation" [VACATION] action. One way to implement
the necessary mechanism for the "duplicate" test is therefore to
@@ -248,6 +271,16 @@
messages when necessary. Messages that are not recognized as
duplicates are stored in the user's inbox as normal.
+
+
+
+
+
+Bosch [Page 5]
+
+ Sieve: Detecting Duplicate Deliveries October 2012
+
+
require ["vnd.dovecot.duplicate", "fileinto", "mailbox"];
if duplicate {
@@ -273,14 +306,6 @@
}
The subjects of the notification message are structured with a
-
-
-
-Bosch [Page 5]
-
- Sieve: Detecting Duplicate Deliveries October 2012
-
-
predictable pattern which includes a description of the event. In
the script above the "duplicate" test is used to detect duplicate
alert events. The message subject is matched against a pattern and
@@ -290,7 +315,7 @@
due to the specified ":seconds" argument. In the the event of a
duplicate, the message is marked as seen using the "imap4flags"
[IMAP4FLAGS] extension. All alert messages are put into the "Alerts"
- mailbox irrespective of wether those messages are duplicates or not.
+ mailbox irrespective of whether those messages are duplicates or not.
6. Security Considerations
@@ -302,8 +327,21 @@
7. References
+
+
+
+
+
+Bosch [Page 6]
+
+ Sieve: Detecting Duplicate Deliveries October 2012
+
+
7.1. Normative References
+ [INCLUDE] Daboo, C. and A. Stone, "Sieve Email Filtering: Include
+ Extension", RFC 6609, May 2012.
+
[KEYWORDS]
Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
@@ -330,13 +368,6 @@
RFC 5229, January 2008.
-
-
-Bosch [Page 6]
-
- Sieve: Detecting Duplicate Deliveries October 2012
-
-
Author's Address
Stephan Bosch
@@ -357,36 +388,5 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Bosch [Page 7]
diff -r 762b6a885897 -r fd7257cb40ea doc/rfc/xml/reference.INCLUDE.xml
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/rfc/xml/reference.INCLUDE.xml Wed Oct 17 21:49:55 2012 +0200
@@ -0,0 +1,17 @@
+<?xml version='1.0' encoding='UTF-8'?>
+
+<reference anchor='INCLUDE'>
+
+<front>
+<title>Sieve Email Filtering: Include Extension</title>
+<author initials='C.' surname='Daboo' fullname='C. Daboo'>
+<organization /></author>
+<author initials='A.' surname='Stone' fullname='A. Stone'>
+<organization /></author>
+<date year='2012' month='May' />
+<abstract>
+<t>The Sieve Email Filtering "include" extension permits users to include one Sieve script inside another. This can make managing large scripts or multiple sets of scripts much easier, and allows a site and its users to build up libraries of scripts. Users are able to include their own personal scripts or site-wide scripts. [STANDARDS-TRACK]</t></abstract></front>
+
+<seriesInfo name='RFC' value='6609' />
+<format type='TXT' octets='26142' target='http://www.rfc-editor.org/rfc/rfc6609.txt' />
+</reference>
diff -r 762b6a885897 -r fd7257cb40ea doc/rfc/xml/spec-bosch-sieve-duplicate.xml
--- a/doc/rfc/xml/spec-bosch-sieve-duplicate.xml Wed Oct 17 02:55:07 2012 +0200
+++ b/doc/rfc/xml/spec-bosch-sieve-duplicate.xml Wed Oct 17 21:49:55 2012 +0200
@@ -113,28 +113,48 @@
extension.</t>
<t>The "duplicate" test evaluates to "true" when the provided value was seen
-before. If the value is not known, the test evaluates to "false" and the value
-is added to an internal value tracking list. Implementations SHOULD limit the
-number of values (and thereby messages) that are tracked. Also, implementations
-SHOULD let entries in the value tracking list expire after a short period of
-time.</t>
+before in an earlier Sieve execution for a previous message delivery. If the
+value was not seen earlier, the test evaluates to "false".</t>
-<t>The user can explicitly control the length this expiration time by means of
-the ":seconds" argument. If the ":seconds" argument is omitted, an appropriate
-default MUST be used. Sites SHOULD impose a maximum limit on the expiration
-time. If that limit is exceeded, the maximum value MUST silently be substituted;
-exceeding the limit MUST NOT produce an error.</t>
+<t>As a side-effect, the "duplicate" test adds the evaluated value to an
+internal duplicate tracking list, so that the test will evaluate to "true" the
+next time the Sieve script is executed and the same value is encountered.
+Note that the "duplicate" test MUST only check for duplicates amongst values
+encountered in previous executions of the Sieve script; it MUST NOT consider
+values encountered earlier in the current Sieve script execution as potential
+duplicates. This means that all "duplicate" tests in a Sieve script execution,
+including those located in scripts included using the "include"
+<xref target="INCLUDE"/> extension, MUST yield the same result if the arguments
+are identical.</t>
-<t>By default the tracked value is the content of the message's Message-ID
+<t>Implementations MUST prevent adding values to the internal duplicate tracking
+list when the Sieve script execution fails. For example, this can be implemented
+by deferring the definitive modification of the tracking list to the end of the
+Sieve script execution. If failed script executions would add values to the
+duplicate tracking list, all "duplicate" tests would erroneously yield "true"
+for the next delivery attempt of the same message, which can -- depending on the
+action taken for a duplicate -- easily lead to discarding the message without
+further notice.</t>
+
+<t>Implementations SHOULD limit the number of values (and thereby messages) that
+are tracked. Also, implementations SHOULD let entries in the value tracking list
+expire after a short period of time. The user can explicitly control the length
+of this expiration time by means of the ":seconds" argument. If the ":seconds"
+argument is omitted, an appropriate default MUST be used. Sites SHOULD impose a
+maximum limit on the expiration time. If that limit is exceeded, the maximum
+value MUST silently be substituted; exceeding the limit MUST NOT produce an
+error.</t>
+
+<t>By default, the tracked value is the content of the message's Message-ID
header field. For more advanced purposes, the content of another header can be
chosen for tracking by specifying the ":header" argument. The tracked string
-value can also be specified explicitly using the ":value" argument. The
+value can also be specified explicitly using the ":value" argument. The
":header" and ":value" arguments are mutually exclusive and specifying both for
a single "duplicate" test command MUST trigger an error at compile time. If the
value is extracted from a header, i.e. when the ":value" argument is not used,
More information about the dovecot-cvs
mailing list