Subject: Commit in docs/usefor (usepro.xml)

From: [email-masked]
Date: Fri, 22 Aug 2008 14:50:30 -0700 (PDT)

Date: Friday, August 22, 2008 @ 14:50:29
  Author: eagle
Revision: 4891

Resolution of #1416.

Introduce the concept of multiple injection, replacing reinjection.  Allow
posting agents to add Injection-Date and require them to do so in the
multiple injection scenario.  Prohibit injecting agents from changing
existing Injection-Date headers.  Prohibit injecting agents from adding
Injection-Date if Date and Message-ID are present but Injection-Date is
missing.  Better explanation of multiple injection and more
recommendations about how to do it properly.

Add an example of a header deprecated for netnews.

Modified:
  docs/usefor/usepro.xml

Modified: docs/usefor/usepro.xml
===================================================================
--- docs/usefor/usepro.xml	2008-08-20 04:58:28 UTC (rev 4890)
+++ docs/usefor/usepro.xml	2008-08-22 21:50:29 UTC (rev 4891)
@@ -18,6 +18,8 @@
     'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2822.xml'>
   <!ENTITY rfc3629 PUBLIC '' 
     'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3629.xml'>
+  <!ENTITY rfc3798 PUBLIC '' 
+    'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3798.xml'>
   <!ENTITY rfc3977 PUBLIC '' 
     'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3977.xml'>
   <!ENTITY rfc4234 PUBLIC '' 
@@ -165,8 +167,9 @@
 
         <t>"Injecting" an article is the processing of a proto-article by
         an injecting agent.  Normally this action is done once and only
-        once for a given article.  "Reinjecting" an article is passing an
-        already-injected article to an injection agent.</t>
+        once for a given article.  "Multiple injection" is passing the
+        same article to multiple injecting agents, either serially or in
+        parallel, by one or several posting agents.</t>
 
         <t>A "gateway" is software which receives news articles and
         converts them to messages of some other kind (such as <xref
@@ -519,10 +522,35 @@
 
         <t>Posting agents SHOULD ensure that proto-articles they create
         are valid according to <xref target="USEFOR" /> and any other
-        applicable policies.  They MUST NOT create any Injection-Date or
-        Injection-Info header fields; these headers will be added by the
-        injecting agent.</t>
+        applicable policies.  They MUST NOT create any Injection-Info
+        header field; this header field may only be added by the injecting
+        agent.</t>
 
+        <t>If the proto-article already contains both Message-ID and Date
+        header fields, posting agents MAY add an Injection-Date header
+        field to that proto-article immediately before passing that
+        proto-article to an injection agent.  They SHOULD do so if the
+        Date header field (representing the composition time of the
+        proto-article) is more than a day in the past at the time of
+        injection.  They MUST do so if the proto-article is being
+        submitted to more than one injecting agent; see <xref
+        target="multi-injection" />.</t>
+
+        <t>The Injection-Date header field is new in this revision of the
+        Netnews protocol and is designed to allow the Date header field to
+        hold the composition date (as recommended in section 3.6.1 of
+        <xref target="RFC2822" />), even if the proto-article is not to be
+        injected for some time after its composition.  However, note that
+        all implementations predating this specification ignore the
+        Injection-Date header field and use the Date header field in its
+        stead for rejecting articles older than their cutoff (see <xref
+        target="history" />), and injecting agents predating this
+        specification do not add an Injection-Date header.  Articles with
+        a Date header field substantially in the past will still be
+        rejected by implementations predating this specification,
+        regardless of the Injection-Date header field, and hence may
+        suffer poorer propagation.</t>
+
         <t>Contrary to <xref target="RFC2822" />, which implies that the
         mailbox or mailboxes in the From header field should be that of
         the poster or posters, a poster who does not, for whatever
@@ -544,48 +572,75 @@
           agent.</t>
 
           <t>A proto-article has the same format as a normal article
-          except that the Injection-Date, Injection-Info, and Xref header
-          fields MUST NOT be present; the Path header field MUST NOT
-          contain a "POSTED" &lt;diag-keyword>; and any of the following
-          mandatory header fields MAY be omitted: Message-ID, Date, and
-          Path.  In all other respects, a proto-article MUST be a valid
-          Netnews article.  In particular, the header fields which may be
-          omitted MUST NOT be present with invalid content.</t>
+          except that the Injection-Info and Xref header fields MUST NOT
+          be present; the Path header field MUST NOT contain a "POSTED"
+          &lt;diag-keyword>; and any of the following mandatory header
+          fields MAY be omitted: Message-ID, Date, and Path.  In all other
+          respects, a proto-article MUST be a valid Netnews article.  In
+          particular, the header fields which may be omitted MUST NOT be
+          present with invalid content.</t>
 
           <t>If a posting agent intends to offer the same proto-article to
-          multiple injecting agents, the header fields Message-ID and Date
-          MUST be present and identical in all copies of the
-          proto-article.</t>
+          multiple injecting agents, the header fields Message-ID, Date,
+          and Injection-Date MUST be present and identical in all copies
+          of the proto-article.  See <xref target="multi-injection" />.</t>
         </section>
 
-        <section anchor="reinjection" title="Reinjection of Articles">
-          <t>A given article SHOULD be processed by an injecting agent
-          once and only once.  The Injection-Date or Injection-Info
-          header fields are added by an injecting agent and are not
-          permitted in a proto-article.  Their presence (or the presence
-          of other unstandardized or obsolete trace headers such as
-          NNTP-Posting-Host, NNTP-Posting-Date, or X-Trace) indicates
-          that the proto-article is instead an article and has already
-          been processed by an injecting agent.  A posting agent SHOULD
-          normally reject such articles.</t>
+        <section anchor="multi-injection"
+                 title="Multiple Injection of Articles">
+          <t>Under some circumstances (posting to multiple disjoint
+          networks, injecting agents with spotty connectivity, or for
+          redundancy, for example), a posting agent may wish to offer the
+          same article to multiple injecting agents.  In this unusual
+          case, the goal is to not create multiple independent articles
+          but rather to inject the same article at multiple points and let
+          the normal duplicate suppression facility of Netnews (see <xref
+          target="history" />) ensure that any given agent accepts the
+          article only once, even if supposedly disjoint networks have
+          unexpected links.</t>
 
-          <t>In the exceptional case that an article needs to be
-          reinjected for some reason (such as transferring an article from
-          one Netnews to another where those networks have no relaying
-          agreement), the posting agent doing the reinjection MUST convert
-          the article back into a proto-article before passing it to an
-          injecting agent (such as by renaming the Injection-Info and
-          Injection-Date header fields and removing any Xref header field)
-          and MUST perform the date checks on the existing Injection-Date
-          or Date header fields that would otherwise be done by the
-          injecting agent.</t>
+          <t>Whenever possible, multiple injection SHOULD be done by
+          offering the same proto-article to multiple injecting agents.
+          The posting agent MUST supply the Message-ID, Date, and
+          Injection-Date header fields, and the proto-article as offered
+          to each injecting agent MUST be identical.</t>
 
-          <t>Reinjecting articles may cause loops, loss of trace
-          information, and other problems and should only be done with
-          care and when there is no available alternative.  A posting
-          agent that does reinjection is a limited type of gateway and as
-          such is subject to all of the requirements of an incoming
-          gateway in addition to the requirements of a posting agent.</t>
+          <t>In some cases, offering the same proto-article to all
+          injecting agents may not be possible (such as when gatewaying,
+          after the fact, articles found on one Netnews network to
+          another, supposedly unconnected one).  In this case, the posting
+          agent MUST convert the article back into a proto-article before
+          passing it to another injecting agent, but it MUST retain
+          unmodified the Message-ID, Date, and Injection-Date header
+          fields.  It MUST NOT add an Injection-Date header field if it is
+          missing from the existing article.  It MUST remove any Xref
+          header field and either rename or remove any Injection-Info
+          header field and other trace fields.
+            <list style="empty">
+              <t>NOTE: Multiple injection inherently risks duplicating
+              articles.  Multiple injection after the fact, by converting
+              an article back to a proto-article and injecting it again,
+              additionally risks loops, loss of trace information,
+              unintended repeat injection into the same network, and other
+              problems.  It should be done with care and only when there
+              is no alternative.  The requirement to retain Message-ID,
+              Date, and Injection-Date header fields minimizes the
+              possibility of a loop and ensures that the newly injected
+              article is not treated as a new, separate article.</t>
+            </list>
+          </t>
+
+          <t>Multiple injection of an article listing one or more
+          moderated newsgroups in its Newsgroups header field SHOULD only
+          be done by a moderator and MUST only be done after the
+          proto-article has been approved for all moderated groups to
+          which it is to be posted and has an Approved header field (see
+          <xref target="moderator" />).  Multiple injection of an
+          unapproved article intended for moderated newsgroups will
+          normally only result in the moderator receiving multiple copies,
+          and if the newsgroup status is not consistent across all
+          injecting agents, may result in duplication of the article or
+          other problems.</t>
         </section>
 
         <section anchor="followups" title="Followups">
@@ -710,23 +765,27 @@
 
             <t>It MUST reject any proto-article that does not have the
             proper mandatory header fields for a proto-article; that has
-            Injection-Date, Injection-Info, or Xref header fields; that
-            has a Path header field containing the "POSTED"
-            &lt;diag-keyword>; or that is not syntactically valid as
-            defined by <xref target="USEFOR" />.  It SHOULD reject any
-            proto-article which contains a header field deprecated for
-            Netnews.  It MAY reject any proto-article that contains trace
-            header fields indicating that it was already injected by an
-            injecting agent that did not add Injection-Info or
-            Injection-Date.</t>
+            Injection-Info or Xref header fields; that has a Path header
+            field containing the "POSTED" &lt;diag-keyword>; or that is
+            not syntactically valid as defined by <xref target="USEFOR"
+            />.  It SHOULD reject any proto-article which contains a
+            header field deprecated for Netnews (see, for example, <xref
+            target="RFC3798" />).  It MAY reject any proto-article that
+            contains trace header fields (e.g., NNTP-Posting-Host)
+            indicating that it was already injected by an injecting agent
+            that did not add Injection-Info or Injection-Date.</t>
 
-            <t>It SHOULD reject any article whose Date header field is
-            more than 24 hours into the future (and MAY use a margin less
-            than 24 hours).  It SHOULD reject any article whose Date
-            header appears to be stale (more than 72 hours into the past,
-            for example, or too old to still be recorded in the database
-            of a relaying agent the injecting agent will be using) since
-            not all news servers support Injection-Date.</t>
+            <t>It SHOULD reject any article whose Injection-Date or Date
+            header field is more than 24 hours into the future (and MAY
+            use a margin less than 24 hours).  It SHOULD reject any
+            article whose Injection-Date header field is too far in the
+            past (older than the cutoff interval of a relaying agent the
+            injecting agent is using, for example).  It SHOULD similarly
+            reject any article whose Date header field is too far in the
+            past, since not all news servers support Injection-Date and
+            only the injecting agent can provide a useful error message to
+            the posting agent.  In either case, this interval SHOULD NOT
+            be any shorter than 72 hours into the past.</t>
 
             <t>It SHOULD reject any proto-article whose Newsgroups header
             field does not contain at least one &lt;newsgroup-name> for a
@@ -770,8 +829,14 @@
             the source of the article and possibly other trace information
             as described in Section 3.2.8 of <xref target="USEFOR" />.</t>
 
-            <t>The injecting agent MUST then add an Injection-Date header
-            field containing the current date and time.</t>
+            <t>If the proto-article already had an Injection-Date header
+            field, it MUST NOT be modified or replaced.  If the
+            proto-article had both a Message-ID header field and a Date
+            header field, an Injection-Date header field MUST NOT be
+            added, since the proto-article may have been multiply injected
+            by a posting agent that predates this standard.  Otherwise,
+            the injecting agent MUST add an Injection-Date header field
+            containing the current date and time.</t>
 
             <t>Finally, the injecting agent forwards the article to one or
             more relaying agents, and the injection process is
@@ -1068,8 +1133,7 @@
             for reasons understood by the moderator (such as delays in the
             moderation process) in which case they MAY substitute the
             current date.  Any Injection-Date, Injection-Info, or Xref
-            header fields already present (though there should be none)
-            MUST be removed.</t>
+            header fields already present MUST be removed.</t>
 
             <t>Any Path header field MUST either be removed or truncated
             to only those entries following its "POSTED"
@@ -2109,6 +2173,7 @@
       &rfc1036;
       &rfc2045;
       &rfc2606;
+      &rfc3798;
       &rfc3977;
       <reference anchor="USEAGE">
         <front>