Initial import.
authorchris <chris@marvin>
Tue, 20 Jan 2009 10:21:03 +0100
changeset 0f907866f0e4b
child 1 6fceb66e1ad7
Initial import.
trunk/AUTHORS
trunk/COPYING
trunk/README
trunk/TODO
trunk/com/so/news/Config.java
trunk/com/so/news/Debug.java
trunk/com/so/news/Main.java
trunk/com/so/news/NNTPConnection.java
trunk/com/so/news/NNTPDaemon.java
trunk/com/so/news/command/ArticleCommand.java
trunk/com/so/news/command/CapabilitiesCommand.java
trunk/com/so/news/command/Command.java
trunk/com/so/news/command/GroupCommand.java
trunk/com/so/news/command/ListCommand.java
trunk/com/so/news/command/ListGroupCommand.java
trunk/com/so/news/command/NewGroupsCommand.java
trunk/com/so/news/command/NextCommand.java
trunk/com/so/news/command/OverCommand.java
trunk/com/so/news/command/PostCommand.java
trunk/com/so/news/io/Resource.java
trunk/com/so/news/storage/Article.java
trunk/com/so/news/storage/Database.java
trunk/com/so/news/storage/Group.java
trunk/com/so/news/storage/Purger.java
trunk/com/so/news/util/StringTemplate.java
trunk/helpers/tbl_mysql6_tmpl.sql
trunk/rfc3977.txt
trunk/test/StringTemplateTest.java
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/trunk/AUTHORS	Tue Jan 20 10:21:03 2009 +0100
     1.3 @@ -0,0 +1,26 @@
     1.4 +AUTHORS & CREDITS
     1.5 +=================
     1.6 +
     1.7 +As most software applications "StarOffice News Server" is based on the work
     1.8 +of individuals or projects. These fine people contributing to the OpenSource
     1.9 +community are mentioned here:
    1.10 +
    1.11 +StarOffice News Server
    1.12 +----------------------
    1.13 +(c)Copyright 2009 by
    1.14 +  * Sun Microsystems, Inc.
    1.15 +  * Christian Lins <christian.lins@sun.com>
    1.16 +
    1.17 +based partly upon
    1.18 +
    1.19 +Neat NNTP Daemon (n3tpd)
    1.20 +------------------------
    1.21 +(c)Copyright 2007, 2008 by Christian Lins <christian.lins@web.de>
    1.22 +
    1.23 +based partly upon
    1.24 +
    1.25 +tnntpd
    1.26 +------
    1.27 +(c)Copyright 2003 by Dennis Schwerdel
    1.28 +
    1.29 +If you find someone missing here, please contact the project leader!
    1.30 \ No newline at end of file
     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/trunk/COPYING	Tue Jan 20 10:21:03 2009 +0100
     2.3 @@ -0,0 +1,674 @@
     2.4 +                    GNU GENERAL PUBLIC LICENSE
     2.5 +                       Version 3, 29 June 2007
     2.6 +
     2.7 + Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
     2.8 + Everyone is permitted to copy and distribute verbatim copies
     2.9 + of this license document, but changing it is not allowed.
    2.10 +
    2.11 +                            Preamble
    2.12 +
    2.13 +  The GNU General Public License is a free, copyleft license for
    2.14 +software and other kinds of works.
    2.15 +
    2.16 +  The licenses for most software and other practical works are designed
    2.17 +to take away your freedom to share and change the works.  By contrast,
    2.18 +the GNU General Public License is intended to guarantee your freedom to
    2.19 +share and change all versions of a program--to make sure it remains free
    2.20 +software for all its users.  We, the Free Software Foundation, use the
    2.21 +GNU General Public License for most of our software; it applies also to
    2.22 +any other work released this way by its authors.  You can apply it to
    2.23 +your programs, too.
    2.24 +
    2.25 +  When we speak of free software, we are referring to freedom, not
    2.26 +price.  Our General Public Licenses are designed to make sure that you
    2.27 +have the freedom to distribute copies of free software (and charge for
    2.28 +them if you wish), that you receive source code or can get it if you
    2.29 +want it, that you can change the software or use pieces of it in new
    2.30 +free programs, and that you know you can do these things.
    2.31 +
    2.32 +  To protect your rights, we need to prevent others from denying you
    2.33 +these rights or asking you to surrender the rights.  Therefore, you have
    2.34 +certain responsibilities if you distribute copies of the software, or if
    2.35 +you modify it: responsibilities to respect the freedom of others.
    2.36 +
    2.37 +  For example, if you distribute copies of such a program, whether
    2.38 +gratis or for a fee, you must pass on to the recipients the same
    2.39 +freedoms that you received.  You must make sure that they, too, receive
    2.40 +or can get the source code.  And you must show them these terms so they
    2.41 +know their rights.
    2.42 +
    2.43 +  Developers that use the GNU GPL protect your rights with two steps:
    2.44 +(1) assert copyright on the software, and (2) offer you this License
    2.45 +giving you legal permission to copy, distribute and/or modify it.
    2.46 +
    2.47 +  For the developers' and authors' protection, the GPL clearly explains
    2.48 +that there is no warranty for this free software.  For both users' and
    2.49 +authors' sake, the GPL requires that modified versions be marked as
    2.50 +changed, so that their problems will not be attributed erroneously to
    2.51 +authors of previous versions.
    2.52 +
    2.53 +  Some devices are designed to deny users access to install or run
    2.54 +modified versions of the software inside them, although the manufacturer
    2.55 +can do so.  This is fundamentally incompatible with the aim of
    2.56 +protecting users' freedom to change the software.  The systematic
    2.57 +pattern of such abuse occurs in the area of products for individuals to
    2.58 +use, which is precisely where it is most unacceptable.  Therefore, we
    2.59 +have designed this version of the GPL to prohibit the practice for those
    2.60 +products.  If such problems arise substantially in other domains, we
    2.61 +stand ready to extend this provision to those domains in future versions
    2.62 +of the GPL, as needed to protect the freedom of users.
    2.63 +
    2.64 +  Finally, every program is threatened constantly by software patents.
    2.65 +States should not allow patents to restrict development and use of
    2.66 +software on general-purpose computers, but in those that do, we wish to
    2.67 +avoid the special danger that patents applied to a free program could
    2.68 +make it effectively proprietary.  To prevent this, the GPL assures that
    2.69 +patents cannot be used to render the program non-free.
    2.70 +
    2.71 +  The precise terms and conditions for copying, distribution and
    2.72 +modification follow.
    2.73 +
    2.74 +                       TERMS AND CONDITIONS
    2.75 +
    2.76 +  0. Definitions.
    2.77 +
    2.78 +  "This License" refers to version 3 of the GNU General Public License.
    2.79 +
    2.80 +  "Copyright" also means copyright-like laws that apply to other kinds of
    2.81 +works, such as semiconductor masks.
    2.82 +
    2.83 +  "The Program" refers to any copyrightable work licensed under this
    2.84 +License.  Each licensee is addressed as "you".  "Licensees" and
    2.85 +"recipients" may be individuals or organizations.
    2.86 +
    2.87 +  To "modify" a work means to copy from or adapt all or part of the work
    2.88 +in a fashion requiring copyright permission, other than the making of an
    2.89 +exact copy.  The resulting work is called a "modified version" of the
    2.90 +earlier work or a work "based on" the earlier work.
    2.91 +
    2.92 +  A "covered work" means either the unmodified Program or a work based
    2.93 +on the Program.
    2.94 +
    2.95 +  To "propagate" a work means to do anything with it that, without
    2.96 +permission, would make you directly or secondarily liable for
    2.97 +infringement under applicable copyright law, except executing it on a
    2.98 +computer or modifying a private copy.  Propagation includes copying,
    2.99 +distribution (with or without modification), making available to the
   2.100 +public, and in some countries other activities as well.
   2.101 +
   2.102 +  To "convey" a work means any kind of propagation that enables other
   2.103 +parties to make or receive copies.  Mere interaction with a user through
   2.104 +a computer network, with no transfer of a copy, is not conveying.
   2.105 +
   2.106 +  An interactive user interface displays "Appropriate Legal Notices"
   2.107 +to the extent that it includes a convenient and prominently visible
   2.108 +feature that (1) displays an appropriate copyright notice, and (2)
   2.109 +tells the user that there is no warranty for the work (except to the
   2.110 +extent that warranties are provided), that licensees may convey the
   2.111 +work under this License, and how to view a copy of this License.  If
   2.112 +the interface presents a list of user commands or options, such as a
   2.113 +menu, a prominent item in the list meets this criterion.
   2.114 +
   2.115 +  1. Source Code.
   2.116 +
   2.117 +  The "source code" for a work means the preferred form of the work
   2.118 +for making modifications to it.  "Object code" means any non-source
   2.119 +form of a work.
   2.120 +
   2.121 +  A "Standard Interface" means an interface that either is an official
   2.122 +standard defined by a recognized standards body, or, in the case of
   2.123 +interfaces specified for a particular programming language, one that
   2.124 +is widely used among developers working in that language.
   2.125 +
   2.126 +  The "System Libraries" of an executable work include anything, other
   2.127 +than the work as a whole, that (a) is included in the normal form of
   2.128 +packaging a Major Component, but which is not part of that Major
   2.129 +Component, and (b) serves only to enable use of the work with that
   2.130 +Major Component, or to implement a Standard Interface for which an
   2.131 +implementation is available to the public in source code form.  A
   2.132 +"Major Component", in this context, means a major essential component
   2.133 +(kernel, window system, and so on) of the specific operating system
   2.134 +(if any) on which the executable work runs, or a compiler used to
   2.135 +produce the work, or an object code interpreter used to run it.
   2.136 +
   2.137 +  The "Corresponding Source" for a work in object code form means all
   2.138 +the source code needed to generate, install, and (for an executable
   2.139 +work) run the object code and to modify the work, including scripts to
   2.140 +control those activities.  However, it does not include the work's
   2.141 +System Libraries, or general-purpose tools or generally available free
   2.142 +programs which are used unmodified in performing those activities but
   2.143 +which are not part of the work.  For example, Corresponding Source
   2.144 +includes interface definition files associated with source files for
   2.145 +the work, and the source code for shared libraries and dynamically
   2.146 +linked subprograms that the work is specifically designed to require,
   2.147 +such as by intimate data communication or control flow between those
   2.148 +subprograms and other parts of the work.
   2.149 +
   2.150 +  The Corresponding Source need not include anything that users
   2.151 +can regenerate automatically from other parts of the Corresponding
   2.152 +Source.
   2.153 +
   2.154 +  The Corresponding Source for a work in source code form is that
   2.155 +same work.
   2.156 +
   2.157 +  2. Basic Permissions.
   2.158 +
   2.159 +  All rights granted under this License are granted for the term of
   2.160 +copyright on the Program, and are irrevocable provided the stated
   2.161 +conditions are met.  This License explicitly affirms your unlimited
   2.162 +permission to run the unmodified Program.  The output from running a
   2.163 +covered work is covered by this License only if the output, given its
   2.164 +content, constitutes a covered work.  This License acknowledges your
   2.165 +rights of fair use or other equivalent, as provided by copyright law.
   2.166 +
   2.167 +  You may make, run and propagate covered works that you do not
   2.168 +convey, without conditions so long as your license otherwise remains
   2.169 +in force.  You may convey covered works to others for the sole purpose
   2.170 +of having them make modifications exclusively for you, or provide you
   2.171 +with facilities for running those works, provided that you comply with
   2.172 +the terms of this License in conveying all material for which you do
   2.173 +not control copyright.  Those thus making or running the covered works
   2.174 +for you must do so exclusively on your behalf, under your direction
   2.175 +and control, on terms that prohibit them from making any copies of
   2.176 +your copyrighted material outside their relationship with you.
   2.177 +
   2.178 +  Conveying under any other circumstances is permitted solely under
   2.179 +the conditions stated below.  Sublicensing is not allowed; section 10
   2.180 +makes it unnecessary.
   2.181 +
   2.182 +  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
   2.183 +
   2.184 +  No covered work shall be deemed part of an effective technological
   2.185 +measure under any applicable law fulfilling obligations under article
   2.186 +11 of the WIPO copyright treaty adopted on 20 December 1996, or
   2.187 +similar laws prohibiting or restricting circumvention of such
   2.188 +measures.
   2.189 +
   2.190 +  When you convey a covered work, you waive any legal power to forbid
   2.191 +circumvention of technological measures to the extent such circumvention
   2.192 +is effected by exercising rights under this License with respect to
   2.193 +the covered work, and you disclaim any intention to limit operation or
   2.194 +modification of the work as a means of enforcing, against the work's
   2.195 +users, your or third parties' legal rights to forbid circumvention of
   2.196 +technological measures.
   2.197 +
   2.198 +  4. Conveying Verbatim Copies.
   2.199 +
   2.200 +  You may convey verbatim copies of the Program's source code as you
   2.201 +receive it, in any medium, provided that you conspicuously and
   2.202 +appropriately publish on each copy an appropriate copyright notice;
   2.203 +keep intact all notices stating that this License and any
   2.204 +non-permissive terms added in accord with section 7 apply to the code;
   2.205 +keep intact all notices of the absence of any warranty; and give all
   2.206 +recipients a copy of this License along with the Program.
   2.207 +
   2.208 +  You may charge any price or no price for each copy that you convey,
   2.209 +and you may offer support or warranty protection for a fee.
   2.210 +
   2.211 +  5. Conveying Modified Source Versions.
   2.212 +
   2.213 +  You may convey a work based on the Program, or the modifications to
   2.214 +produce it from the Program, in the form of source code under the
   2.215 +terms of section 4, provided that you also meet all of these conditions:
   2.216 +
   2.217 +    a) The work must carry prominent notices stating that you modified
   2.218 +    it, and giving a relevant date.
   2.219 +
   2.220 +    b) The work must carry prominent notices stating that it is
   2.221 +    released under this License and any conditions added under section
   2.222 +    7.  This requirement modifies the requirement in section 4 to
   2.223 +    "keep intact all notices".
   2.224 +
   2.225 +    c) You must license the entire work, as a whole, under this
   2.226 +    License to anyone who comes into possession of a copy.  This
   2.227 +    License will therefore apply, along with any applicable section 7
   2.228 +    additional terms, to the whole of the work, and all its parts,
   2.229 +    regardless of how they are packaged.  This License gives no
   2.230 +    permission to license the work in any other way, but it does not
   2.231 +    invalidate such permission if you have separately received it.
   2.232 +
   2.233 +    d) If the work has interactive user interfaces, each must display
   2.234 +    Appropriate Legal Notices; however, if the Program has interactive
   2.235 +    interfaces that do not display Appropriate Legal Notices, your
   2.236 +    work need not make them do so.
   2.237 +
   2.238 +  A compilation of a covered work with other separate and independent
   2.239 +works, which are not by their nature extensions of the covered work,
   2.240 +and which are not combined with it such as to form a larger program,
   2.241 +in or on a volume of a storage or distribution medium, is called an
   2.242 +"aggregate" if the compilation and its resulting copyright are not
   2.243 +used to limit the access or legal rights of the compilation's users
   2.244 +beyond what the individual works permit.  Inclusion of a covered work
   2.245 +in an aggregate does not cause this License to apply to the other
   2.246 +parts of the aggregate.
   2.247 +
   2.248 +  6. Conveying Non-Source Forms.
   2.249 +
   2.250 +  You may convey a covered work in object code form under the terms
   2.251 +of sections 4 and 5, provided that you also convey the
   2.252 +machine-readable Corresponding Source under the terms of this License,
   2.253 +in one of these ways:
   2.254 +
   2.255 +    a) Convey the object code in, or embodied in, a physical product
   2.256 +    (including a physical distribution medium), accompanied by the
   2.257 +    Corresponding Source fixed on a durable physical medium
   2.258 +    customarily used for software interchange.
   2.259 +
   2.260 +    b) Convey the object code in, or embodied in, a physical product
   2.261 +    (including a physical distribution medium), accompanied by a
   2.262 +    written offer, valid for at least three years and valid for as
   2.263 +    long as you offer spare parts or customer support for that product
   2.264 +    model, to give anyone who possesses the object code either (1) a
   2.265 +    copy of the Corresponding Source for all the software in the
   2.266 +    product that is covered by this License, on a durable physical
   2.267 +    medium customarily used for software interchange, for a price no
   2.268 +    more than your reasonable cost of physically performing this
   2.269 +    conveying of source, or (2) access to copy the
   2.270 +    Corresponding Source from a network server at no charge.
   2.271 +
   2.272 +    c) Convey individual copies of the object code with a copy of the
   2.273 +    written offer to provide the Corresponding Source.  This
   2.274 +    alternative is allowed only occasionally and noncommercially, and
   2.275 +    only if you received the object code with such an offer, in accord
   2.276 +    with subsection 6b.
   2.277 +
   2.278 +    d) Convey the object code by offering access from a designated
   2.279 +    place (gratis or for a charge), and offer equivalent access to the
   2.280 +    Corresponding Source in the same way through the same place at no
   2.281 +    further charge.  You need not require recipients to copy the
   2.282 +    Corresponding Source along with the object code.  If the place to
   2.283 +    copy the object code is a network server, the Corresponding Source
   2.284 +    may be on a different server (operated by you or a third party)
   2.285 +    that supports equivalent copying facilities, provided you maintain
   2.286 +    clear directions next to the object code saying where to find the
   2.287 +    Corresponding Source.  Regardless of what server hosts the
   2.288 +    Corresponding Source, you remain obligated to ensure that it is
   2.289 +    available for as long as needed to satisfy these requirements.
   2.290 +
   2.291 +    e) Convey the object code using peer-to-peer transmission, provided
   2.292 +    you inform other peers where the object code and Corresponding
   2.293 +    Source of the work are being offered to the general public at no
   2.294 +    charge under subsection 6d.
   2.295 +
   2.296 +  A separable portion of the object code, whose source code is excluded
   2.297 +from the Corresponding Source as a System Library, need not be
   2.298 +included in conveying the object code work.
   2.299 +
   2.300 +  A "User Product" is either (1) a "consumer product", which means any
   2.301 +tangible personal property which is normally used for personal, family,
   2.302 +or household purposes, or (2) anything designed or sold for incorporation
   2.303 +into a dwelling.  In determining whether a product is a consumer product,
   2.304 +doubtful cases shall be resolved in favor of coverage.  For a particular
   2.305 +product received by a particular user, "normally used" refers to a
   2.306 +typical or common use of that class of product, regardless of the status
   2.307 +of the particular user or of the way in which the particular user
   2.308 +actually uses, or expects or is expected to use, the product.  A product
   2.309 +is a consumer product regardless of whether the product has substantial
   2.310 +commercial, industrial or non-consumer uses, unless such uses represent
   2.311 +the only significant mode of use of the product.
   2.312 +
   2.313 +  "Installation Information" for a User Product means any methods,
   2.314 +procedures, authorization keys, or other information required to install
   2.315 +and execute modified versions of a covered work in that User Product from
   2.316 +a modified version of its Corresponding Source.  The information must
   2.317 +suffice to ensure that the continued functioning of the modified object
   2.318 +code is in no case prevented or interfered with solely because
   2.319 +modification has been made.
   2.320 +
   2.321 +  If you convey an object code work under this section in, or with, or
   2.322 +specifically for use in, a User Product, and the conveying occurs as
   2.323 +part of a transaction in which the right of possession and use of the
   2.324 +User Product is transferred to the recipient in perpetuity or for a
   2.325 +fixed term (regardless of how the transaction is characterized), the
   2.326 +Corresponding Source conveyed under this section must be accompanied
   2.327 +by the Installation Information.  But this requirement does not apply
   2.328 +if neither you nor any third party retains the ability to install
   2.329 +modified object code on the User Product (for example, the work has
   2.330 +been installed in ROM).
   2.331 +
   2.332 +  The requirement to provide Installation Information does not include a
   2.333 +requirement to continue to provide support service, warranty, or updates
   2.334 +for a work that has been modified or installed by the recipient, or for
   2.335 +the User Product in which it has been modified or installed.  Access to a
   2.336 +network may be denied when the modification itself materially and
   2.337 +adversely affects the operation of the network or violates the rules and
   2.338 +protocols for communication across the network.
   2.339 +
   2.340 +  Corresponding Source conveyed, and Installation Information provided,
   2.341 +in accord with this section must be in a format that is publicly
   2.342 +documented (and with an implementation available to the public in
   2.343 +source code form), and must require no special password or key for
   2.344 +unpacking, reading or copying.
   2.345 +
   2.346 +  7. Additional Terms.
   2.347 +
   2.348 +  "Additional permissions" are terms that supplement the terms of this
   2.349 +License by making exceptions from one or more of its conditions.
   2.350 +Additional permissions that are applicable to the entire Program shall
   2.351 +be treated as though they were included in this License, to the extent
   2.352 +that they are valid under applicable law.  If additional permissions
   2.353 +apply only to part of the Program, that part may be used separately
   2.354 +under those permissions, but the entire Program remains governed by
   2.355 +this License without regard to the additional permissions.
   2.356 +
   2.357 +  When you convey a copy of a covered work, you may at your option
   2.358 +remove any additional permissions from that copy, or from any part of
   2.359 +it.  (Additional permissions may be written to require their own
   2.360 +removal in certain cases when you modify the work.)  You may place
   2.361 +additional permissions on material, added by you to a covered work,
   2.362 +for which you have or can give appropriate copyright permission.
   2.363 +
   2.364 +  Notwithstanding any other provision of this License, for material you
   2.365 +add to a covered work, you may (if authorized by the copyright holders of
   2.366 +that material) supplement the terms of this License with terms:
   2.367 +
   2.368 +    a) Disclaiming warranty or limiting liability differently from the
   2.369 +    terms of sections 15 and 16 of this License; or
   2.370 +
   2.371 +    b) Requiring preservation of specified reasonable legal notices or
   2.372 +    author attributions in that material or in the Appropriate Legal
   2.373 +    Notices displayed by works containing it; or
   2.374 +
   2.375 +    c) Prohibiting misrepresentation of the origin of that material, or
   2.376 +    requiring that modified versions of such material be marked in
   2.377 +    reasonable ways as different from the original version; or
   2.378 +
   2.379 +    d) Limiting the use for publicity purposes of names of licensors or
   2.380 +    authors of the material; or
   2.381 +
   2.382 +    e) Declining to grant rights under trademark law for use of some
   2.383 +    trade names, trademarks, or service marks; or
   2.384 +
   2.385 +    f) Requiring indemnification of licensors and authors of that
   2.386 +    material by anyone who conveys the material (or modified versions of
   2.387 +    it) with contractual assumptions of liability to the recipient, for
   2.388 +    any liability that these contractual assumptions directly impose on
   2.389 +    those licensors and authors.
   2.390 +
   2.391 +  All other non-permissive additional terms are considered "further
   2.392 +restrictions" within the meaning of section 10.  If the Program as you
   2.393 +received it, or any part of it, contains a notice stating that it is
   2.394 +governed by this License along with a term that is a further
   2.395 +restriction, you may remove that term.  If a license document contains
   2.396 +a further restriction but permits relicensing or conveying under this
   2.397 +License, you may add to a covered work material governed by the terms
   2.398 +of that license document, provided that the further restriction does
   2.399 +not survive such relicensing or conveying.
   2.400 +
   2.401 +  If you add terms to a covered work in accord with this section, you
   2.402 +must place, in the relevant source files, a statement of the
   2.403 +additional terms that apply to those files, or a notice indicating
   2.404 +where to find the applicable terms.
   2.405 +
   2.406 +  Additional terms, permissive or non-permissive, may be stated in the
   2.407 +form of a separately written license, or stated as exceptions;
   2.408 +the above requirements apply either way.
   2.409 +
   2.410 +  8. Termination.
   2.411 +
   2.412 +  You may not propagate or modify a covered work except as expressly
   2.413 +provided under this License.  Any attempt otherwise to propagate or
   2.414 +modify it is void, and will automatically terminate your rights under
   2.415 +this License (including any patent licenses granted under the third
   2.416 +paragraph of section 11).
   2.417 +
   2.418 +  However, if you cease all violation of this License, then your
   2.419 +license from a particular copyright holder is reinstated (a)
   2.420 +provisionally, unless and until the copyright holder explicitly and
   2.421 +finally terminates your license, and (b) permanently, if the copyright
   2.422 +holder fails to notify you of the violation by some reasonable means
   2.423 +prior to 60 days after the cessation.
   2.424 +
   2.425 +  Moreover, your license from a particular copyright holder is
   2.426 +reinstated permanently if the copyright holder notifies you of the
   2.427 +violation by some reasonable means, this is the first time you have
   2.428 +received notice of violation of this License (for any work) from that
   2.429 +copyright holder, and you cure the violation prior to 30 days after
   2.430 +your receipt of the notice.
   2.431 +
   2.432 +  Termination of your rights under this section does not terminate the
   2.433 +licenses of parties who have received copies or rights from you under
   2.434 +this License.  If your rights have been terminated and not permanently
   2.435 +reinstated, you do not qualify to receive new licenses for the same
   2.436 +material under section 10.
   2.437 +
   2.438 +  9. Acceptance Not Required for Having Copies.
   2.439 +
   2.440 +  You are not required to accept this License in order to receive or
   2.441 +run a copy of the Program.  Ancillary propagation of a covered work
   2.442 +occurring solely as a consequence of using peer-to-peer transmission
   2.443 +to receive a copy likewise does not require acceptance.  However,
   2.444 +nothing other than this License grants you permission to propagate or
   2.445 +modify any covered work.  These actions infringe copyright if you do
   2.446 +not accept this License.  Therefore, by modifying or propagating a
   2.447 +covered work, you indicate your acceptance of this License to do so.
   2.448 +
   2.449 +  10. Automatic Licensing of Downstream Recipients.
   2.450 +
   2.451 +  Each time you convey a covered work, the recipient automatically
   2.452 +receives a license from the original licensors, to run, modify and
   2.453 +propagate that work, subject to this License.  You are not responsible
   2.454 +for enforcing compliance by third parties with this License.
   2.455 +
   2.456 +  An "entity transaction" is a transaction transferring control of an
   2.457 +organization, or substantially all assets of one, or subdividing an
   2.458 +organization, or merging organizations.  If propagation of a covered
   2.459 +work results from an entity transaction, each party to that
   2.460 +transaction who receives a copy of the work also receives whatever
   2.461 +licenses to the work the party's predecessor in interest had or could
   2.462 +give under the previous paragraph, plus a right to possession of the
   2.463 +Corresponding Source of the work from the predecessor in interest, if
   2.464 +the predecessor has it or can get it with reasonable efforts.
   2.465 +
   2.466 +  You may not impose any further restrictions on the exercise of the
   2.467 +rights granted or affirmed under this License.  For example, you may
   2.468 +not impose a license fee, royalty, or other charge for exercise of
   2.469 +rights granted under this License, and you may not initiate litigation
   2.470 +(including a cross-claim or counterclaim in a lawsuit) alleging that
   2.471 +any patent claim is infringed by making, using, selling, offering for
   2.472 +sale, or importing the Program or any portion of it.
   2.473 +
   2.474 +  11. Patents.
   2.475 +
   2.476 +  A "contributor" is a copyright holder who authorizes use under this
   2.477 +License of the Program or a work on which the Program is based.  The
   2.478 +work thus licensed is called the contributor's "contributor version".
   2.479 +
   2.480 +  A contributor's "essential patent claims" are all patent claims
   2.481 +owned or controlled by the contributor, whether already acquired or
   2.482 +hereafter acquired, that would be infringed by some manner, permitted
   2.483 +by this License, of making, using, or selling its contributor version,
   2.484 +but do not include claims that would be infringed only as a
   2.485 +consequence of further modification of the contributor version.  For
   2.486 +purposes of this definition, "control" includes the right to grant
   2.487 +patent sublicenses in a manner consistent with the requirements of
   2.488 +this License.
   2.489 +
   2.490 +  Each contributor grants you a non-exclusive, worldwide, royalty-free
   2.491 +patent license under the contributor's essential patent claims, to
   2.492 +make, use, sell, offer for sale, import and otherwise run, modify and
   2.493 +propagate the contents of its contributor version.
   2.494 +
   2.495 +  In the following three paragraphs, a "patent license" is any express
   2.496 +agreement or commitment, however denominated, not to enforce a patent
   2.497 +(such as an express permission to practice a patent or covenant not to
   2.498 +sue for patent infringement).  To "grant" such a patent license to a
   2.499 +party means to make such an agreement or commitment not to enforce a
   2.500 +patent against the party.
   2.501 +
   2.502 +  If you convey a covered work, knowingly relying on a patent license,
   2.503 +and the Corresponding Source of the work is not available for anyone
   2.504 +to copy, free of charge and under the terms of this License, through a
   2.505 +publicly available network server or other readily accessible means,
   2.506 +then you must either (1) cause the Corresponding Source to be so
   2.507 +available, or (2) arrange to deprive yourself of the benefit of the
   2.508 +patent license for this particular work, or (3) arrange, in a manner
   2.509 +consistent with the requirements of this License, to extend the patent
   2.510 +license to downstream recipients.  "Knowingly relying" means you have
   2.511 +actual knowledge that, but for the patent license, your conveying the
   2.512 +covered work in a country, or your recipient's use of the covered work
   2.513 +in a country, would infringe one or more identifiable patents in that
   2.514 +country that you have reason to believe are valid.
   2.515 +
   2.516 +  If, pursuant to or in connection with a single transaction or
   2.517 +arrangement, you convey, or propagate by procuring conveyance of, a
   2.518 +covered work, and grant a patent license to some of the parties
   2.519 +receiving the covered work authorizing them to use, propagate, modify
   2.520 +or convey a specific copy of the covered work, then the patent license
   2.521 +you grant is automatically extended to all recipients of the covered
   2.522 +work and works based on it.
   2.523 +
   2.524 +  A patent license is "discriminatory" if it does not include within
   2.525 +the scope of its coverage, prohibits the exercise of, or is
   2.526 +conditioned on the non-exercise of one or more of the rights that are
   2.527 +specifically granted under this License.  You may not convey a covered
   2.528 +work if you are a party to an arrangement with a third party that is
   2.529 +in the business of distributing software, under which you make payment
   2.530 +to the third party based on the extent of your activity of conveying
   2.531 +the work, and under which the third party grants, to any of the
   2.532 +parties who would receive the covered work from you, a discriminatory
   2.533 +patent license (a) in connection with copies of the covered work
   2.534 +conveyed by you (or copies made from those copies), or (b) primarily
   2.535 +for and in connection with specific products or compilations that
   2.536 +contain the covered work, unless you entered into that arrangement,
   2.537 +or that patent license was granted, prior to 28 March 2007.
   2.538 +
   2.539 +  Nothing in this License shall be construed as excluding or limiting
   2.540 +any implied license or other defenses to infringement that may
   2.541 +otherwise be available to you under applicable patent law.
   2.542 +
   2.543 +  12. No Surrender of Others' Freedom.
   2.544 +
   2.545 +  If conditions are imposed on you (whether by court order, agreement or
   2.546 +otherwise) that contradict the conditions of this License, they do not
   2.547 +excuse you from the conditions of this License.  If you cannot convey a
   2.548 +covered work so as to satisfy simultaneously your obligations under this
   2.549 +License and any other pertinent obligations, then as a consequence you may
   2.550 +not convey it at all.  For example, if you agree to terms that obligate you
   2.551 +to collect a royalty for further conveying from those to whom you convey
   2.552 +the Program, the only way you could satisfy both those terms and this
   2.553 +License would be to refrain entirely from conveying the Program.
   2.554 +
   2.555 +  13. Use with the GNU Affero General Public License.
   2.556 +
   2.557 +  Notwithstanding any other provision of this License, you have
   2.558 +permission to link or combine any covered work with a work licensed
   2.559 +under version 3 of the GNU Affero General Public License into a single
   2.560 +combined work, and to convey the resulting work.  The terms of this
   2.561 +License will continue to apply to the part which is the covered work,
   2.562 +but the special requirements of the GNU Affero General Public License,
   2.563 +section 13, concerning interaction through a network will apply to the
   2.564 +combination as such.
   2.565 +
   2.566 +  14. Revised Versions of this License.
   2.567 +
   2.568 +  The Free Software Foundation may publish revised and/or new versions of
   2.569 +the GNU General Public License from time to time.  Such new versions will
   2.570 +be similar in spirit to the present version, but may differ in detail to
   2.571 +address new problems or concerns.
   2.572 +
   2.573 +  Each version is given a distinguishing version number.  If the
   2.574 +Program specifies that a certain numbered version of the GNU General
   2.575 +Public License "or any later version" applies to it, you have the
   2.576 +option of following the terms and conditions either of that numbered
   2.577 +version or of any later version published by the Free Software
   2.578 +Foundation.  If the Program does not specify a version number of the
   2.579 +GNU General Public License, you may choose any version ever published
   2.580 +by the Free Software Foundation.
   2.581 +
   2.582 +  If the Program specifies that a proxy can decide which future
   2.583 +versions of the GNU General Public License can be used, that proxy's
   2.584 +public statement of acceptance of a version permanently authorizes you
   2.585 +to choose that version for the Program.
   2.586 +
   2.587 +  Later license versions may give you additional or different
   2.588 +permissions.  However, no additional obligations are imposed on any
   2.589 +author or copyright holder as a result of your choosing to follow a
   2.590 +later version.
   2.591 +
   2.592 +  15. Disclaimer of Warranty.
   2.593 +
   2.594 +  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
   2.595 +APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
   2.596 +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
   2.597 +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
   2.598 +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   2.599 +PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
   2.600 +IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
   2.601 +ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
   2.602 +
   2.603 +  16. Limitation of Liability.
   2.604 +
   2.605 +  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   2.606 +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
   2.607 +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
   2.608 +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
   2.609 +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
   2.610 +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
   2.611 +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
   2.612 +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
   2.613 +SUCH DAMAGES.
   2.614 +
   2.615 +  17. Interpretation of Sections 15 and 16.
   2.616 +
   2.617 +  If the disclaimer of warranty and limitation of liability provided
   2.618 +above cannot be given local legal effect according to their terms,
   2.619 +reviewing courts shall apply local law that most closely approximates
   2.620 +an absolute waiver of all civil liability in connection with the
   2.621 +Program, unless a warranty or assumption of liability accompanies a
   2.622 +copy of the Program in return for a fee.
   2.623 +
   2.624 +                     END OF TERMS AND CONDITIONS
   2.625 +
   2.626 +            How to Apply These Terms to Your New Programs
   2.627 +
   2.628 +  If you develop a new program, and you want it to be of the greatest
   2.629 +possible use to the public, the best way to achieve this is to make it
   2.630 +free software which everyone can redistribute and change under these terms.
   2.631 +
   2.632 +  To do so, attach the following notices to the program.  It is safest
   2.633 +to attach them to the start of each source file to most effectively
   2.634 +state the exclusion of warranty; and each file should have at least
   2.635 +the "copyright" line and a pointer to where the full notice is found.
   2.636 +
   2.637 +    <one line to give the program's name and a brief idea of what it does.>
   2.638 +    Copyright (C) <year>  <name of author>
   2.639 +
   2.640 +    This program is free software: you can redistribute it and/or modify
   2.641 +    it under the terms of the GNU General Public License as published by
   2.642 +    the Free Software Foundation, either version 3 of the License, or
   2.643 +    (at your option) any later version.
   2.644 +
   2.645 +    This program is distributed in the hope that it will be useful,
   2.646 +    but WITHOUT ANY WARRANTY; without even the implied warranty of
   2.647 +    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   2.648 +    GNU General Public License for more details.
   2.649 +
   2.650 +    You should have received a copy of the GNU General Public License
   2.651 +    along with this program.  If not, see <http://www.gnu.org/licenses/>.
   2.652 +
   2.653 +Also add information on how to contact you by electronic and paper mail.
   2.654 +
   2.655 +  If the program does terminal interaction, make it output a short
   2.656 +notice like this when it starts in an interactive mode:
   2.657 +
   2.658 +    <program>  Copyright (C) <year>  <name of author>
   2.659 +    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
   2.660 +    This is free software, and you are welcome to redistribute it
   2.661 +    under certain conditions; type `show c' for details.
   2.662 +
   2.663 +The hypothetical commands `show w' and `show c' should show the appropriate
   2.664 +parts of the General Public License.  Of course, your program's commands
   2.665 +might be different; for a GUI interface, you would use an "about box".
   2.666 +
   2.667 +  You should also get your employer (if you work as a programmer) or school,
   2.668 +if any, to sign a "copyright disclaimer" for the program, if necessary.
   2.669 +For more information on this, and how to apply and follow the GNU GPL, see
   2.670 +<http://www.gnu.org/licenses/>.
   2.671 +
   2.672 +  The GNU General Public License does not permit incorporating your program
   2.673 +into proprietary programs.  If your program is a subroutine library, you
   2.674 +may consider it more useful to permit linking proprietary applications with
   2.675 +the library.  If this is what you want to do, use the GNU Lesser General
   2.676 +Public License instead of this License.  But first, please read
   2.677 +<http://www.gnu.org/philosophy/why-not-lgpl.html>.
   2.678 \ No newline at end of file
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/trunk/README	Tue Jan 20 10:21:03 2009 +0100
     3.3 @@ -0,0 +1,24 @@
     3.4 +n3tpd README
     3.5 +============
     3.6 +
     3.7 +Prerequisites:
     3.8 +--------------
     3.9 +
    3.10 +* Java Runtime, Version 1.5
    3.11 +* MySQL, Version 5 or higher
    3.12 +* Java-MySQL-Connector (JDBC driver)
    3.13 +
    3.14 +
    3.15 +Installation:
    3.16 +-------------
    3.17 +
    3.18 +* Create a database in your DBMS, e.g. named like 'n3tpd_data'
    3.19 +* Create the necessary table structure using the helpers/table.sql file
    3.20 +* Customize the settings within the n3tpd.conf file
    3.21 +* Invoke 'java -jar n3tpd.jar' to start the daemon
    3.22 +
    3.23 +Bugs and other Issues:
    3.24 +----------------------
    3.25 +
    3.26 +Please mail them to christian.lins@web.de or, better, issue them
    3.27 +into our bugtracker at http://bugs.netvader.net/ .
    3.28 \ No newline at end of file
     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/trunk/TODO	Tue Jan 20 10:21:03 2009 +0100
     4.3 @@ -0,0 +1,10 @@
     4.4 +TODO
     4.5 +====
     4.6 +
     4.7 +* Implement new SQL table structure
     4.8 +* Implement a --init-tables command that creates the necessary database/tables
     4.9 +
    4.10 +ROADMAP
    4.11 +=======
    4.12 +
    4.13 +Version 1.0 must be fully RFC3977 compliant.
    4.14 \ No newline at end of file
     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/trunk/com/so/news/Config.java	Tue Jan 20 10:21:03 2009 +0100
     5.3 @@ -0,0 +1,198 @@
     5.4 +/*
     5.5 + *   StarOffice News Server
     5.6 + *   see AUTHORS for the list of contributors
     5.7 + *
     5.8 + *   This program is free software: you can redistribute it and/or modify
     5.9 + *   it under the terms of the GNU General Public License as published by
    5.10 + *   the Free Software Foundation, either version 3 of the License, or
    5.11 + *   (at your option) any later version.
    5.12 + *
    5.13 + *   This program is distributed in the hope that it will be useful,
    5.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
    5.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    5.16 + *   GNU General Public License for more details.
    5.17 + *
    5.18 + *   You should have received a copy of the GNU General Public License
    5.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
    5.20 + */
    5.21 +
    5.22 +package com.so.news;
    5.23 +
    5.24 +import java.io.FileInputStream;
    5.25 +import java.io.FileNotFoundException;
    5.26 +import java.io.FileOutputStream;
    5.27 +import java.io.IOException;
    5.28 +import java.util.Properties;
    5.29 +
    5.30 +/**
    5.31 + * Manages the n3tpd configuration.
    5.32 + * @author Christian Lins
    5.33 + */
    5.34 +public class Config
    5.35 +{
    5.36 +  /** The filename of the logfile */
    5.37 +  public static final String CONFIG_N3TPD_LOGFILE = "n3tpd.logfile";
    5.38 +  
    5.39 +  /** The filename of the config file that is loaded on startup */
    5.40 +  public static final String FILE                 = "n3tpd.conf";
    5.41 +
    5.42 +  private static final Properties defaultConfig = new Properties();
    5.43 +  
    5.44 +  private static Config instance = null;
    5.45 +  
    5.46 +  static
    5.47 +  {
    5.48 +    // Set some default values
    5.49 +    defaultConfig.setProperty("n3tpd.article.lifetime", "300"); // 300 days
    5.50 +    defaultConfig.setProperty("n3tpd.article.maxsize", "100");  // 100 kbyte
    5.51 +    defaultConfig.setProperty("n3tpd.port", "119");
    5.52 +    defaultConfig.setProperty("n3tpd.auxport", "8080");
    5.53 +    defaultConfig.setProperty("n3tpd.server.backlog", "10");
    5.54 +    defaultConfig.setProperty("n3tpd.hostname", "localhost");
    5.55 +    defaultConfig.setProperty("n3tpd.storage.database", "jdbc:mysql://localhost/n3tpd_data");
    5.56 +    defaultConfig.setProperty("n3tpd.storage.dbmsdriver", "com.mysql.jdbc.Driver");
    5.57 +    defaultConfig.setProperty("n3tpd.storage.user", "n3tpd_user");
    5.58 +    defaultConfig.setProperty("n3tpd.storage.password", "mysecret");
    5.59 +    
    5.60 +    instance = new Config();
    5.61 +  }
    5.62 +  
    5.63 +  /**
    5.64 +   * @return A Config instance
    5.65 +   */
    5.66 +  public static Config getInstance()
    5.67 +  {
    5.68 +    return instance;
    5.69 +  }
    5.70 +
    5.71 +  // Every config instance is initialized with the default values.
    5.72 +  private Properties settings = (Properties)defaultConfig.clone();
    5.73 +
    5.74 +  /**
    5.75 +   * Config is a singelton class with only one instance at time.
    5.76 +   * So the constructor is private to prevent the creation of more
    5.77 +   * then one Config instance.
    5.78 +   * @see Config.getInstance() to retrieve an instance of Config
    5.79 +   */
    5.80 +  private Config()
    5.81 +  {
    5.82 +    try
    5.83 +    {
    5.84 +      // Load settings from file
    5.85 +      load();
    5.86 +    }
    5.87 +    catch(IOException e)
    5.88 +    {
    5.89 +      e.printStackTrace();
    5.90 +    }
    5.91 +  }
    5.92 +
    5.93 +  /**
    5.94 +   * Loads the configuration from the config file. By default this is done
    5.95 +   * by the (private) constructor but it can be useful to reload the config
    5.96 +   * by invoking this method.
    5.97 +   * @throws IOException
    5.98 +   */
    5.99 +  public void load() throws IOException
   5.100 +  {
   5.101 +    try
   5.102 +    {
   5.103 +      settings.load(new FileInputStream(FILE));
   5.104 +    }
   5.105 +    catch (FileNotFoundException e)
   5.106 +    {
   5.107 +      save();
   5.108 +    }
   5.109 +  }
   5.110 +
   5.111 +  /**
   5.112 +   * Saves this Config to the config file. By default this is done
   5.113 +   * at program end.
   5.114 +   * @throws FileNotFoundException
   5.115 +   * @throws IOException
   5.116 +   */
   5.117 +  public void save() throws FileNotFoundException, IOException
   5.118 +  {
   5.119 +    settings.store(new FileOutputStream(FILE), "N3TPD Config File");
   5.120 +  }
   5.121 +  
   5.122 +  /**
   5.123 +   * Returns the value that is stored within this config
   5.124 +   * identified by the given key. If the key cannot be found
   5.125 +   * the default value is returned.
   5.126 +   * @param key Key to identify the value.
   5.127 +   * @param def The default value that is returned if the key
   5.128 +   * is not found in this Config.
   5.129 +   * @return
   5.130 +   */
   5.131 +  public String get(String key, String def)
   5.132 +  {
   5.133 +    return settings.getProperty(key, def);
   5.134 +  }
   5.135 +
   5.136 +  /**
   5.137 +   * Returns the value that is stored within this config
   5.138 +   * identified by the given key. If the key cannot be found
   5.139 +   * the default value is returned.
   5.140 +   * @param key Key to identify the value.
   5.141 +   * @param def The default value that is returned if the key
   5.142 +   * is not found in this Config.
   5.143 +   * @return
   5.144 +   */
   5.145 +  public int get(String key, int def)
   5.146 +  {
   5.147 +    try
   5.148 +    {
   5.149 +      String val = get(key);
   5.150 +      return Integer.parseInt(val);
   5.151 +    }
   5.152 +    catch(Exception e)
   5.153 +    {
   5.154 +      return def;
   5.155 +    }
   5.156 +  }
   5.157 +  
   5.158 +  /**
   5.159 +   * Returns the value that is stored within this config
   5.160 +   * identified by the given key. If the key cannot be found
   5.161 +   * the default value is returned.
   5.162 +   * @param key Key to identify the value.
   5.163 +   * @param def The default value that is returned if the key
   5.164 +   * is not found in this Config.
   5.165 +   * @return
   5.166 +   */
   5.167 +  public long get(String key, long def)
   5.168 +  {
   5.169 +    try
   5.170 +    {
   5.171 +      String val = get(key);
   5.172 +      return Long.parseLong(val);
   5.173 +    }
   5.174 +    catch(Exception e)
   5.175 +    {
   5.176 +      return def;
   5.177 +    }
   5.178 +  }
   5.179 +
   5.180 +  /**
   5.181 +   * Returns the value for the given key or null if the
   5.182 +   * key is not found in this Config.
   5.183 +   * @param key
   5.184 +   * @return
   5.185 +   */
   5.186 +  private String get(String key)
   5.187 +  {
   5.188 +    return settings.getProperty(key);
   5.189 +  }
   5.190 +
   5.191 +  /**
   5.192 +   * Sets the value for a given key.
   5.193 +   * @param key
   5.194 +   * @param value
   5.195 +   */
   5.196 +  public void set(String key, String value)
   5.197 +  {
   5.198 +    settings.setProperty(key, value);
   5.199 +  }
   5.200 +
   5.201 +}
     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/trunk/com/so/news/Debug.java	Tue Jan 20 10:21:03 2009 +0100
     6.3 @@ -0,0 +1,95 @@
     6.4 +/*
     6.5 + *   StarOffice News Server
     6.6 + *   see AUTHORS for the list of contributors
     6.7 + *
     6.8 + *   This program is free software: you can redistribute it and/or modify
     6.9 + *   it under the terms of the GNU General Public License as published by
    6.10 + *   the Free Software Foundation, either version 3 of the License, or
    6.11 + *   (at your option) any later version.
    6.12 + *
    6.13 + *   This program is distributed in the hope that it will be useful,
    6.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
    6.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    6.16 + *   GNU General Public License for more details.
    6.17 + *
    6.18 + *   You should have received a copy of the GNU General Public License
    6.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
    6.20 + */
    6.21 +
    6.22 +package com.so.news;
    6.23 +
    6.24 +import java.io.FileOutputStream;
    6.25 +import java.io.IOException;
    6.26 +import java.io.PrintStream;
    6.27 +import java.util.Date;
    6.28 +
    6.29 +/**
    6.30 + * Provides logging and debugging methods.
    6.31 + * @author Christian Lins
    6.32 + */
    6.33 +public class Debug
    6.34 +{
    6.35 +  private static Debug instance = null;
    6.36 +  
    6.37 +  /**
    6.38 +   * Returns the singelton instance of this class.
    6.39 +   */
    6.40 +  public static Debug getInstance()
    6.41 +  {
    6.42 +    if(instance == null)
    6.43 +      instance = new Debug();
    6.44 +    
    6.45 +    return instance;
    6.46 +  }
    6.47 +  
    6.48 +  private PrintStream out = System.err;
    6.49 +  
    6.50 +  /**
    6.51 +   * This class is a singelton class. The constructor is private to prevent
    6.52 +   * the creation of more than one instance.
    6.53 +   */
    6.54 +  private Debug()
    6.55 +  {
    6.56 +    try
    6.57 +    {
    6.58 +      String filename = Config.getInstance().get(Config.CONFIG_N3TPD_LOGFILE, "n3tpd.log");
    6.59 +      
    6.60 +      this.out = new PrintStream(new FileOutputStream(filename));
    6.61 +    }
    6.62 +    catch(IOException e)
    6.63 +    {
    6.64 +      e.printStackTrace();
    6.65 +    }
    6.66 +  }
    6.67 +  
    6.68 +  /**
    6.69 +   * Returns the debug output PrintStream. By default this is System.err.
    6.70 +   */
    6.71 +  public PrintStream getStream()
    6.72 +  {
    6.73 +    return out;
    6.74 +  }
    6.75 +  
    6.76 +  /**
    6.77 +   * Writes the given message to the debug output.
    6.78 +   * @param msg A String message or an object.
    6.79 +   */
    6.80 +  public void log(Object msg)
    6.81 +  {
    6.82 +    log(out, msg);
    6.83 +    log(System.out, msg);
    6.84 +  }
    6.85 +  
    6.86 +  /**
    6.87 +   * Writes the given debug message to the given PrintStream.
    6.88 +   * @param out
    6.89 +   * @param msg
    6.90 +   */
    6.91 +  public void log(PrintStream out, Object msg)
    6.92 +  {
    6.93 +    out.print(new Date().toString());
    6.94 +    out.print(": ");
    6.95 +    out.println(msg.toString());
    6.96 +    out.flush();
    6.97 +  }
    6.98 +}
     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/trunk/com/so/news/Main.java	Tue Jan 20 10:21:03 2009 +0100
     7.3 @@ -0,0 +1,96 @@
     7.4 +/*
     7.5 + *   StarOffice News Server
     7.6 + *   see AUTHORS for the list of contributors
     7.7 + *
     7.8 + *   This program is free software: you can redistribute it and/or modify
     7.9 + *   it under the terms of the GNU General Public License as published by
    7.10 + *   the Free Software Foundation, either version 3 of the License, or
    7.11 + *   (at your option) any later version.
    7.12 + *
    7.13 + *   This program is distributed in the hope that it will be useful,
    7.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
    7.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    7.16 + *   GNU General Public License for more details.
    7.17 + *
    7.18 + *   You should have received a copy of the GNU General Public License
    7.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
    7.20 + */
    7.21 +
    7.22 +package com.so.news;
    7.23 +
    7.24 +import java.net.BindException;
    7.25 +
    7.26 +import java.sql.Driver;
    7.27 +import java.sql.DriverManager;
    7.28 +import java.util.Enumeration;
    7.29 +
    7.30 +import com.so.news.storage.Database;
    7.31 +import com.so.news.storage.Purger;
    7.32 +
    7.33 +/**
    7.34 + * Startup class of the daemon.
    7.35 + * @author Christian Lins
    7.36 + */
    7.37 +public class Main
    7.38 +{
    7.39 +  /** Version information of the StarOffice News daemon */
    7.40 +  public static final String VERSION = "StarOffice News Server 0.5alpha1";
    7.41 +
    7.42 +  /**
    7.43 +   * The main entrypoint.
    7.44 +   * @param args
    7.45 +   * @throws Exception
    7.46 +   */
    7.47 +  public static void main(String args[]) throws Exception
    7.48 +  {
    7.49 +    System.out.println(VERSION);
    7.50 +
    7.51 +    // Command line arguments
    7.52 +    boolean auxPort = false;
    7.53 +    
    7.54 +    for(int n = 0; n < args.length; n++)
    7.55 +    {
    7.56 +      if(args[n].equals("--dumpjdbcdriver"))
    7.57 +      {
    7.58 +        System.out.println("Available JDBC drivers:");
    7.59 +        Enumeration<Driver> drvs =  DriverManager.getDrivers();
    7.60 +        while(drvs.hasMoreElements())
    7.61 +          System.out.println(drvs.nextElement());
    7.62 +        return;
    7.63 +      }
    7.64 +      else if(args[n].equals("--useaux"))
    7.65 +        auxPort = true;
    7.66 +    }
    7.67 +    
    7.68 +    // Try to load the Database
    7.69 +    try
    7.70 +    {
    7.71 +      Database.arise();
    7.72 +    }
    7.73 +    catch(Exception ex)
    7.74 +    {
    7.75 +      ex.printStackTrace(Debug.getInstance().getStream());
    7.76 +      System.err.println("Database initialization failed with " + ex.toString());
    7.77 +      
    7.78 +      return;
    7.79 +    }
    7.80 +    
    7.81 +    // Start the n3tpd garbage collector
    7.82 +    new Purger().start();
    7.83 +    
    7.84 +    // Start the listening daemon
    7.85 +    try
    7.86 +    {
    7.87 +      new NNTPDaemon(false).start();
    7.88 +    }
    7.89 +    catch(BindException ex)
    7.90 +    {
    7.91 +      ex.printStackTrace(Debug.getInstance().getStream());
    7.92 +      System.err.println("Could not bind to interface. Perhaps you need superuser rights?");
    7.93 +    }
    7.94 +    
    7.95 +    // Start auxilary listening port...
    7.96 +    if(auxPort)
    7.97 +      new NNTPDaemon(true).start();
    7.98 +  }
    7.99 +}
     8.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     8.2 +++ b/trunk/com/so/news/NNTPConnection.java	Tue Jan 20 10:21:03 2009 +0100
     8.3 @@ -0,0 +1,395 @@
     8.4 +/*
     8.5 + *   StarOffice News Server
     8.6 + *   see AUTHORS for the list of contributors
     8.7 + *
     8.8 + *   This program is free software: you can redistribute it and/or modify
     8.9 + *   it under the terms of the GNU General Public License as published by
    8.10 + *   the Free Software Foundation, either version 3 of the License, or
    8.11 + *   (at your option) any later version.
    8.12 + *
    8.13 + *   This program is distributed in the hope that it will be useful,
    8.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
    8.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    8.16 + *   GNU General Public License for more details.
    8.17 + *
    8.18 + *   You should have received a copy of the GNU General Public License
    8.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
    8.20 + */
    8.21 +
    8.22 +package com.so.news;
    8.23 +
    8.24 +import java.io.BufferedReader;
    8.25 +import java.io.BufferedWriter;
    8.26 +import java.io.File;
    8.27 +import java.io.InputStreamReader;
    8.28 +import java.io.IOException;
    8.29 +import java.io.OutputStreamWriter;
    8.30 +import java.net.Socket;
    8.31 +import java.net.SocketException;
    8.32 +import java.text.SimpleDateFormat;
    8.33 +import java.util.Date;
    8.34 +import java.util.LinkedList;
    8.35 +import java.util.List;
    8.36 +import com.so.news.command.ArticleCommand;
    8.37 +import com.so.news.command.GroupCommand;
    8.38 +import com.so.news.command.ListCommand;
    8.39 +import com.so.news.command.PostCommand;
    8.40 +import com.so.news.command.OverCommand;
    8.41 +import com.so.news.storage.Article;
    8.42 +import com.so.news.storage.Group;
    8.43 +
    8.44 +/**
    8.45 + * Represents the connection between the server and one client.
    8.46 + * @author Christian Lins (christian.lins@web.de)
    8.47 + */
    8.48 +public class NNTPConnection extends Thread
    8.49 +{
    8.50 +  public static final String NEWLINE            = "\r\n";
    8.51 +  public static final String MESSAGE_ID_PATTERN = "<[^>]+>";
    8.52 +  
    8.53 +  private boolean            debug              
    8.54 +    = Boolean.parseBoolean(Config.getInstance().get("n3tpd.debug", "false"));
    8.55 +  private Socket             socket;
    8.56 +  private boolean            exit               = false;
    8.57 +  private BufferedWriter     out;
    8.58 +  private BufferedReader     in;
    8.59 +  private Article            currentArticle     = null;
    8.60 +  private Group              currentGroup       = null;
    8.61 +
    8.62 +  /**
    8.63 +   * Creates a new NNTPConnection instance using the given connected Socket.
    8.64 +   * @param socket
    8.65 +   * @throws java.io.IOException
    8.66 +   */
    8.67 +  public NNTPConnection(Socket socket) 
    8.68 +    throws IOException
    8.69 +  {
    8.70 +    this.socket = socket;
    8.71 +    this.in     = new BufferedReader(new InputStreamReader(socket.getInputStream()));
    8.72 +    this.out    = new BufferedWriter(new OutputStreamWriter(socket.getOutputStream()));
    8.73 +    // TODO: The output stream should be of type PrintStream so that many
    8.74 +    // of the printX() methods of this class can go to trash
    8.75 +    
    8.76 +    setDaemon(true); // Exits if the main thread is killed
    8.77 +  }
    8.78 +
    8.79 +  /**
    8.80 +   * Closes the associated socket end exits the Thread.
    8.81 +   */
    8.82 +  public void exit()
    8.83 +  {
    8.84 +    try
    8.85 +    {
    8.86 +      exit = true;
    8.87 +      socket.close();
    8.88 +    }
    8.89 +    catch (Exception e)
    8.90 +    {
    8.91 +      e.printStackTrace();
    8.92 +    }
    8.93 +  }
    8.94 +
    8.95 +  /**
    8.96 +   * Prints a CharSequence to the sockets output stream.
    8.97 +   */
    8.98 +  public void print(CharSequence s) throws IOException
    8.99 +  {
   8.100 +    out.append(s);
   8.101 +  }
   8.102 +
   8.103 +  public void println(CharSequence s) throws IOException
   8.104 +  {
   8.105 +    print(s);
   8.106 +    print(NEWLINE);
   8.107 +    if (debug)
   8.108 +      System.out.println("<<< " + s);
   8.109 +  }
   8.110 +
   8.111 +  public void printStatus(int code, String description) throws IOException
   8.112 +  {
   8.113 +    println("" + code + " " + description);
   8.114 +    flush();
   8.115 +  }
   8.116 +
   8.117 +  public void printTextLine(CharSequence line) throws IOException
   8.118 +  {
   8.119 +    if (line.length() > 0 && line.charAt(0) == '.')
   8.120 +      print("..");
   8.121 +    println(line);
   8.122 +  }
   8.123 +
   8.124 +  public void printTextPart(CharSequence text) throws IOException
   8.125 +  {
   8.126 +    String[] lines = text.toString().split(NEWLINE);
   8.127 +    for (String line : lines)
   8.128 +      printTextLine(line);
   8.129 +  }
   8.130 +
   8.131 +  public void printText(CharSequence text) throws IOException
   8.132 +  {
   8.133 +    printTextPart(text);
   8.134 +    println(".");
   8.135 +    flush();
   8.136 +  }
   8.137 +
   8.138 +  public void flush() throws IOException
   8.139 +  {
   8.140 +    out.flush();
   8.141 +  }
   8.142 +
   8.143 +  public String readln() throws IOException
   8.144 +  {
   8.145 +    String s = in.readLine();
   8.146 +    if (s == null)
   8.147 +      throw new IOException("Socket closed");
   8.148 +    if (debug)
   8.149 +      System.out.println(">>> " + s);
   8.150 +    return s;
   8.151 +  }
   8.152 +
   8.153 +  public String[] readCommand() throws IOException
   8.154 +  {
   8.155 +    return readln().split("[ ]+");
   8.156 +  }
   8.157 +
   8.158 +  public List<String> readText() throws IOException
   8.159 +  {
   8.160 +    List<String> l = new LinkedList<String>();
   8.161 +    String s;
   8.162 +    do
   8.163 +    {
   8.164 +      s = readln();
   8.165 +      if (!s.equals("."))
   8.166 +      {
   8.167 +        if (s.startsWith(".."))
   8.168 +          s = s.substring(1);
   8.169 +        l.add(s);
   8.170 +      }
   8.171 +    }
   8.172 +    while (!s.equals("."));
   8.173 +    return l;
   8.174 +  }
   8.175 +
   8.176 +  public String readTextLine() throws IOException
   8.177 +  {
   8.178 +    String s = null;
   8.179 +    do
   8.180 +    {
   8.181 +      s = readln();
   8.182 +    }
   8.183 +    while (s == null);
   8.184 +    if (s.equals("."))
   8.185 +      return null;
   8.186 +    if (s.startsWith(".."))
   8.187 +      s = s.substring(1);
   8.188 +    return s;
   8.189 +  }
   8.190 +
   8.191 +  public void setCurrentArticle(Article current)
   8.192 +  {
   8.193 +    currentArticle = current;
   8.194 +  }
   8.195 +
   8.196 +  public Article getCurrentArticle()
   8.197 +  {
   8.198 +    return currentArticle;
   8.199 +  }
   8.200 +
   8.201 +  public void setCurrentGroup(Group current)
   8.202 +  {
   8.203 +    currentGroup = current;
   8.204 +  }
   8.205 +
   8.206 +  public Group getCurrentGroup()
   8.207 +  {
   8.208 +    return currentGroup;
   8.209 +  }
   8.210 +
   8.211 +  private void processCommand(String[] command) 
   8.212 +    throws Exception
   8.213 +  {
   8.214 +    if (command.length == 0)
   8.215 +      return; // TODO Error
   8.216 +
   8.217 +    String commandName = command[0];
   8.218 +
   8.219 +    // RFC977
   8.220 +    // TODO HELP command
   8.221 +    // TODO NEWGROUPS command
   8.222 +    // TODO NEWNEWS command
   8.223 +
   8.224 +    // RFC2980
   8.225 +    // TODO LIST ACTIVE command
   8.226 +    // TODO LIST ACTIVE.TIMES command
   8.227 +    // TODO LIST DISTRIBUTIONS command
   8.228 +    // TODO LIST DISTRIB.PATS command
   8.229 +    // TODO XGTITLE command
   8.230 +    // TODO XHDR command
   8.231 +    // TODO XPAT command
   8.232 +    // TODO XPATH command
   8.233 +    // TODO XROVER command
   8.234 +    // TODO XTHREAD command
   8.235 +    // TODO AUTHINFO command
   8.236 +
   8.237 +    // STANDARD COMMANDS
   8.238 +    if (commandName.equalsIgnoreCase("ARTICLE")
   8.239 +        || commandName.equalsIgnoreCase("STAT")
   8.240 +        || commandName.equalsIgnoreCase("HEAD") 
   8.241 +        || commandName.equalsIgnoreCase("BODY"))
   8.242 +    {
   8.243 +      ArticleCommand cmd = new ArticleCommand(this);
   8.244 +      cmd.process(command);
   8.245 +    }
   8.246 +    
   8.247 +    else if (commandName.equalsIgnoreCase("LIST"))
   8.248 +    {
   8.249 +      ListCommand cmd = new ListCommand(this);
   8.250 +      cmd.process(command);
   8.251 +    }
   8.252 +
   8.253 +    else if (commandName.equalsIgnoreCase("GROUP"))
   8.254 +    {
   8.255 +      GroupCommand cmd = new GroupCommand(this);
   8.256 +      cmd.process(command);
   8.257 +    }
   8.258 +    
   8.259 +    else if(commandName.equalsIgnoreCase("POST"))
   8.260 +    {
   8.261 +      PostCommand cmd = new PostCommand(this);
   8.262 +      cmd.process(command);
   8.263 +    }
   8.264 +
   8.265 +    else if (commandName.equalsIgnoreCase("CHECK")
   8.266 +        || commandName.equalsIgnoreCase("TAKETHIS"))
   8.267 +    {
   8.268 +      // untested, RFC2980 compliant
   8.269 +      printStatus(400, "not accepting articles");
   8.270 +      return;
   8.271 +    }
   8.272 +
   8.273 +    else if (commandName.equalsIgnoreCase("IHAVE")
   8.274 +        || commandName.equalsIgnoreCase("XREPLIC"))
   8.275 +    {
   8.276 +      // untested, RFC977 compliant
   8.277 +      printStatus(435, "article not wanted - do not send it");
   8.278 +      return;
   8.279 +    }
   8.280 +
   8.281 +    else if (commandName.equalsIgnoreCase("XCREATEGROUP"))
   8.282 +    {
   8.283 +      return;
   8.284 +    }
   8.285 +
   8.286 +    else if (commandName.equalsIgnoreCase("SLAVE"))
   8.287 +    {
   8.288 +      // untested, RFC977 compliant
   8.289 +      printStatus(202, "slave status noted");
   8.290 +      return;
   8.291 +    }
   8.292 +
   8.293 +    else if (commandName.equalsIgnoreCase("XINDEX"))
   8.294 +    {
   8.295 +      // untested, RFC2980 compliant
   8.296 +      printStatus(418, "no tin-style index is available for this news group");
   8.297 +      return;
   8.298 +    }
   8.299 +
   8.300 +    else if (commandName.equalsIgnoreCase("DATE"))
   8.301 +    {
   8.302 +      printStatus(111, new SimpleDateFormat("yyyyMMddHHmmss")
   8.303 +          .format(new Date()));
   8.304 +      return;
   8.305 +    }
   8.306 +
   8.307 +    else if (commandName.equalsIgnoreCase("MODE"))
   8.308 +    {
   8.309 +      if (command[1].equalsIgnoreCase("READER"))
   8.310 +      {
   8.311 +        // untested, RFC2980 compliant
   8.312 +        printStatus(200, "Hello, you can post");
   8.313 +      }
   8.314 +      else if (command[1].equalsIgnoreCase("STREAM"))
   8.315 +      {
   8.316 +        printStatus(203, "Streaming is OK");
   8.317 +      }
   8.318 +      else
   8.319 +        printStatus(501, "Command not supported");
   8.320 +    }
   8.321 +
   8.322 +    else if (commandName.equalsIgnoreCase("QUIT"))
   8.323 +    {
   8.324 +      // untested, RFC977 compliant
   8.325 +      printStatus(205, "closing connection - goodbye!");
   8.326 +      exit();
   8.327 +      return;
   8.328 +    }  
   8.329 +    
   8.330 +    else if (commandName.equalsIgnoreCase("XSHUTDOWN"))
   8.331 +    {
   8.332 +      printStatus(205, "closing connection - goodbye!");
   8.333 +      exit();
   8.334 +      return;
   8.335 +    }
   8.336 +
   8.337 +    // X COMMANDS
   8.338 +    else if(commandName.equalsIgnoreCase("XOVER")
   8.339 +       || commandName.equalsIgnoreCase("OVER"))
   8.340 +    {
   8.341 +      OverCommand cmd = new OverCommand(this);
   8.342 +      cmd.process(command);
   8.343 +    }
   8.344 +
   8.345 +    else
   8.346 +      printStatus(501, "Command not supported");
   8.347 +  }
   8.348 +
   8.349 +  /**
   8.350 +   * Runloop of this Thread.
   8.351 +   * @throws RuntimeException if this method is called directly.
   8.352 +   */
   8.353 +  @Override
   8.354 +  public void run()
   8.355 +  {
   8.356 +    assert !this.equals(Thread.currentThread());
   8.357 +
   8.358 +    try
   8.359 +    {
   8.360 +      printStatus(200, Config.getInstance().get("n3tpd.hostname", "localhost")
   8.361 +          + " " + Main.VERSION + " news server ready - (posting ok).");
   8.362 +    }
   8.363 +    catch (IOException e1)
   8.364 +    {
   8.365 +      exit();
   8.366 +    }
   8.367 +    
   8.368 +    while (!exit)
   8.369 +    {
   8.370 +      try
   8.371 +      {
   8.372 +        processCommand(readCommand());
   8.373 +      }
   8.374 +      catch (SocketException e)
   8.375 +      {
   8.376 +        if (exit)
   8.377 +          return;
   8.378 +        exit();
   8.379 +        e.printStackTrace();
   8.380 +      }
   8.381 +      catch (IOException e)
   8.382 +      {
   8.383 +        if (exit)
   8.384 +          return;
   8.385 +        exit();
   8.386 +        e.printStackTrace();
   8.387 +      }
   8.388 +      catch (Throwable e)
   8.389 +      {
   8.390 +        if (exit)
   8.391 +          return;
   8.392 +        e.printStackTrace();
   8.393 +        // silently ignore
   8.394 +      }
   8.395 +    }
   8.396 +  }
   8.397 +
   8.398 +}
     9.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.2 +++ b/trunk/com/so/news/NNTPDaemon.java	Tue Jan 20 10:21:03 2009 +0100
     9.3 @@ -0,0 +1,64 @@
     9.4 +/*
     9.5 + *   StarOffice News Server
     9.6 + *   see AUTHORS for the list of contributors
     9.7 + *
     9.8 + *   This program is free software: you can redistribute it and/or modify
     9.9 + *   it under the terms of the GNU General Public License as published by
    9.10 + *   the Free Software Foundation, either version 3 of the License, or
    9.11 + *   (at your option) any later version.
    9.12 + *
    9.13 + *   This program is distributed in the hope that it will be useful,
    9.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
    9.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    9.16 + *   GNU General Public License for more details.
    9.17 + *
    9.18 + *   You should have received a copy of the GNU General Public License
    9.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
    9.20 + */
    9.21 +
    9.22 +package com.so.news;
    9.23 +
    9.24 +import java.io.IOException;
    9.25 +import java.net.ServerSocket;
    9.26 +
    9.27 +/**
    9.28 + * Server component of the n3tpd.
    9.29 + * @author Christian Lins
    9.30 + * @author Dennis Schwerdel
    9.31 + */
    9.32 +public class NNTPDaemon extends Thread
    9.33 +{
    9.34 +  private ServerSocket socket;
    9.35 +
    9.36 +  public NNTPDaemon(boolean aux) throws IOException
    9.37 +  {
    9.38 +    int port; 
    9.39 +    if(!aux)
    9.40 +      port = Config.getInstance().get("n3tpd.port", 119);
    9.41 +    else
    9.42 +      port = Config.getInstance().get("n3tpd.auxport", 8080);
    9.43 +    
    9.44 +    int backlog = Config.getInstance().get("n3tpd.server.backlog", 10);
    9.45 +    
    9.46 +    // Create and bind the socket
    9.47 +    socket = new ServerSocket(port, backlog);
    9.48 +  }
    9.49 +
    9.50 +  @Override
    9.51 +  public void run()
    9.52 +  {
    9.53 +    System.out.println("Daemon listening on port " + socket.getLocalPort() + " ...");
    9.54 +    
    9.55 +    while(isAlive() && !isInterrupted())
    9.56 +    {
    9.57 +      try
    9.58 +      {
    9.59 +        new NNTPConnection(socket.accept()).start();
    9.60 +      }
    9.61 +      catch (Exception e)
    9.62 +      {
    9.63 +        e.printStackTrace();
    9.64 +      }
    9.65 +    }
    9.66 +  }
    9.67 +}
    10.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    10.2 +++ b/trunk/com/so/news/command/ArticleCommand.java	Tue Jan 20 10:21:03 2009 +0100
    10.3 @@ -0,0 +1,124 @@
    10.4 +/*
    10.5 + *   StarOffice News Server
    10.6 + *   see AUTHORS for the list of contributors
    10.7 + *
    10.8 + *   This program is free software: you can redistribute it and/or modify
    10.9 + *   it under the terms of the GNU General Public License as published by
   10.10 + *   the Free Software Foundation, either version 3 of the License, or
   10.11 + *   (at your option) any later version.
   10.12 + *
   10.13 + *   This program is distributed in the hope that it will be useful,
   10.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   10.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   10.16 + *   GNU General Public License for more details.
   10.17 + *
   10.18 + *   You should have received a copy of the GNU General Public License
   10.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   10.20 + */
   10.21 +
   10.22 +package com.so.news.command;
   10.23 +
   10.24 +import java.io.IOException;
   10.25 +import java.text.SimpleDateFormat;
   10.26 +import java.util.Locale;
   10.27 +import java.util.Map;
   10.28 +import com.so.news.Debug;
   10.29 +import com.so.news.NNTPConnection;
   10.30 +import com.so.news.storage.Article;
   10.31 +
   10.32 +/**
   10.33 + * Class handling the ARTICLE command.
   10.34 + * @author Christian Lins
   10.35 + * @author Dennis Schwerdel
   10.36 + */
   10.37 +public class ArticleCommand extends Command
   10.38 +{
   10.39 +  public ArticleCommand(NNTPConnection connection)
   10.40 +  {
   10.41 +    super(connection);
   10.42 +  }
   10.43 +
   10.44 +  public boolean process(String[] command) throws IOException
   10.45 +  {
   10.46 +    String commandName = command[0];
   10.47 +
   10.48 +    // untested, RFC977 compliant
   10.49 +    Article article = null;
   10.50 +    if (command.length <= 1)
   10.51 +    {
   10.52 +      article = getCurrentArticle();
   10.53 +      if (article == null)
   10.54 +      {
   10.55 +        printStatus(420, "no current article has been selected");
   10.56 +        return true;
   10.57 +      }
   10.58 +    }
   10.59 +    else if (command[1].matches(NNTPConnection.MESSAGE_ID_PATTERN))
   10.60 +    {
   10.61 +      // Message-ID
   10.62 +      article = Article.getByMessageID(command[1]);
   10.63 +      if (article == null)
   10.64 +      {
   10.65 +        printStatus(430, "no such article found");
   10.66 +        return true;
   10.67 +      }
   10.68 +    }
   10.69 +    else
   10.70 +    {
   10.71 +      // Message Number
   10.72 +      try
   10.73 +      {
   10.74 +        int num = Integer.parseInt(command[1]);
   10.75 +        article = Article.getByNumberInGroup(connection.getCurrentGroup(), num);
   10.76 +      }
   10.77 +      catch (Exception ex)
   10.78 +      {
   10.79 +        ex.printStackTrace(Debug.getInstance().getStream());
   10.80 +        System.err.println(ex.getLocalizedMessage());
   10.81 +      }
   10.82 +      if (article == null)
   10.83 +      {
   10.84 +        printStatus(423, "no such article number in this group");
   10.85 +        return true;
   10.86 +      }
   10.87 +      setCurrentArticle(article);
   10.88 +    }
   10.89 +
   10.90 +    if (commandName.equalsIgnoreCase("ARTICLE"))
   10.91 +    {
   10.92 +      printStatus(220, article.getNumberInGroup() + " " + article.getMessageID()
   10.93 +          + " article retrieved - head and body follow");
   10.94 +      Map<String, String> header = article.getHeader();
   10.95 +      for(Map.Entry<String, String> entry : header.entrySet())
   10.96 +      {
   10.97 +        if(entry.getKey().equals("Date"))
   10.98 +        {
   10.99 +          SimpleDateFormat sdf = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss Z", Locale.US);
  10.100 +          printTextPart("Date: " + sdf.format(article.getDate()));
  10.101 +        }
  10.102 +        else
  10.103 +          printTextPart(entry.getKey() + ": " + entry.getValue());
  10.104 +      }
  10.105 +      println("");
  10.106 +      printText(article.getBody());
  10.107 +    }
  10.108 +    else if (commandName.equalsIgnoreCase("HEAD"))
  10.109 +    {
  10.110 +      printStatus(500, "No longer supported! Use XOVER instead.");
  10.111 +      return false;
  10.112 +    }
  10.113 +    else if (commandName.equalsIgnoreCase("BODY"))
  10.114 +    {
  10.115 +      printStatus(222, article.getNumberInGroup() + " " + article.getMessageID()
  10.116 +          + " body");
  10.117 +      printText(article.getBody());
  10.118 +    }
  10.119 +    else if (commandName.equalsIgnoreCase("STAT"))
  10.120 +    {
  10.121 +      printStatus(223, article.getNumberInGroup() + " " + article.getMessageID()
  10.122 +          + " article retrieved - request text separately");
  10.123 +    }
  10.124 +    return true;
  10.125 +  }
  10.126 +
  10.127 +}
    11.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    11.2 +++ b/trunk/com/so/news/command/CapabilitiesCommand.java	Tue Jan 20 10:21:03 2009 +0100
    11.3 @@ -0,0 +1,50 @@
    11.4 +/*
    11.5 + *   StarOffice News Server
    11.6 + *   see AUTHORS for the list of contributors
    11.7 + *
    11.8 + *   This program is free software: you can redistribute it and/or modify
    11.9 + *   it under the terms of the GNU General Public License as published by
   11.10 + *   the Free Software Foundation, either version 3 of the License, or
   11.11 + *   (at your option) any later version.
   11.12 + *
   11.13 + *   This program is distributed in the hope that it will be useful,
   11.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   11.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   11.16 + *   GNU General Public License for more details.
   11.17 + *
   11.18 + *   You should have received a copy of the GNU General Public License
   11.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   11.20 + */
   11.21 +
   11.22 +package com.so.news.command;
   11.23 +
   11.24 +import com.so.news.NNTPConnection;
   11.25 +
   11.26 +/**
   11.27 + *   The CAPABILITIES command allows a client to determine the
   11.28 +   capabilities of the server at any given time.
   11.29 +
   11.30 +   This command MAY be issued at any time; the server MUST NOT require
   11.31 +   it to be issued in order to make use of any capability.  The response
   11.32 +   generated by this command MAY change during a session because of
   11.33 +   other state information (which, in turn, may be changed by the
   11.34 +   effects of other commands or by external events).  An NNTP client is
   11.35 +   only able to get the current and correct information concerning
   11.36 +   available capabilities at any point during a session by issuing a
   11.37 +   CAPABILITIES command at that point of that session and processing the
   11.38 +   response.
   11.39 + * @author chris
   11.40 + */
   11.41 +public class CapabilitiesCommand extends Command
   11.42 +{
   11.43 +  public CapabilitiesCommand(NNTPConnection connection)
   11.44 +  {
   11.45 +    super(connection);
   11.46 +  }
   11.47 +  
   11.48 +  public boolean process(String[] command)
   11.49 +    throws Exception
   11.50 +  {
   11.51 +    return false;
   11.52 +  }
   11.53 +}
    12.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    12.2 +++ b/trunk/com/so/news/command/Command.java	Tue Jan 20 10:21:03 2009 +0100
    12.3 @@ -0,0 +1,106 @@
    12.4 +/*
    12.5 + *   StarOffice News Server
    12.6 + *   see AUTHORS for the list of contributors
    12.7 + *
    12.8 + *   This program is free software: you can redistribute it and/or modify
    12.9 + *   it under the terms of the GNU General Public License as published by
   12.10 + *   the Free Software Foundation, either version 3 of the License, or
   12.11 + *   (at your option) any later version.
   12.12 + *
   12.13 + *   This program is distributed in the hope that it will be useful,
   12.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   12.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   12.16 + *   GNU General Public License for more details.
   12.17 + *
   12.18 + *   You should have received a copy of the GNU General Public License
   12.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   12.20 + */
   12.21 +
   12.22 +package com.so.news.command;
   12.23 +
   12.24 +import java.io.IOException;
   12.25 +import java.util.List;
   12.26 +import com.so.news.NNTPConnection;
   12.27 +import com.so.news.storage.Article;
   12.28 +import com.so.news.storage.Group;
   12.29 +
   12.30 +/**
   12.31 + * Base class for all command handling classes.
   12.32 + * @author Christian Lins
   12.33 + * @author Dennis Schwerdel
   12.34 + */
   12.35 +public abstract class Command
   12.36 +{
   12.37 +  protected NNTPConnection connection;
   12.38 +
   12.39 +  public Command(NNTPConnection connection)
   12.40 +  {
   12.41 +    this.connection = connection;
   12.42 +  }
   12.43 +
   12.44 +  protected static String NEWLINE = NNTPConnection.NEWLINE;
   12.45 +
   12.46 +  protected List<String> readText() 
   12.47 +    throws IOException
   12.48 +  {
   12.49 +    return connection.readText();
   12.50 +  }
   12.51 +
   12.52 +  protected String readTextLine() throws IOException
   12.53 +  {
   12.54 +    return connection.readTextLine();
   12.55 +  }
   12.56 +
   12.57 +  protected void printStatus(int status, String text) throws IOException
   12.58 +  {
   12.59 +    connection.printStatus(status, text);
   12.60 +  }
   12.61 +
   12.62 +  protected void printTextLine(CharSequence text) throws IOException
   12.63 +  {
   12.64 +    connection.printTextLine(text);
   12.65 +  }
   12.66 +
   12.67 +  protected void printTextPart(CharSequence text) throws IOException
   12.68 +  {
   12.69 +    connection.printTextPart(text);
   12.70 +  }
   12.71 +  
   12.72 +  protected void printText(CharSequence text) throws IOException
   12.73 +  {
   12.74 +    connection.printText(text);
   12.75 +  }
   12.76 +
   12.77 +  protected void println(CharSequence text) throws IOException
   12.78 +  {
   12.79 +    connection.println(text);
   12.80 +  }
   12.81 +
   12.82 +  protected void flush() throws IOException
   12.83 +  {
   12.84 +    connection.flush();
   12.85 +  }
   12.86 +
   12.87 +  protected Article getCurrentArticle()
   12.88 +  {
   12.89 +    return connection.getCurrentArticle();
   12.90 +  }
   12.91 +
   12.92 +  protected Group getCurrentGroup()
   12.93 +  {
   12.94 +    return connection.getCurrentGroup();
   12.95 +  }
   12.96 +
   12.97 +  protected void setCurrentArticle(Article current)
   12.98 +  {
   12.99 +    connection.setCurrentArticle(current);
  12.100 +  }
  12.101 +
  12.102 +  protected void setCurrentGroup(Group current)
  12.103 +  {
  12.104 +    connection.setCurrentGroup(current);
  12.105 +  }
  12.106 +
  12.107 +  public abstract boolean process(String[] command)
  12.108 +    throws Exception;
  12.109 +}
    13.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    13.2 +++ b/trunk/com/so/news/command/GroupCommand.java	Tue Jan 20 10:21:03 2009 +0100
    13.3 @@ -0,0 +1,60 @@
    13.4 +/*
    13.5 + *   StarOffice News Server
    13.6 + *   see AUTHORS for the list of contributors
    13.7 + *
    13.8 + *   This program is free software: you can redistribute it and/or modify
    13.9 + *   it under the terms of the GNU General Public License as published by
   13.10 + *   the Free Software Foundation, either version 3 of the License, or
   13.11 + *   (at your option) any later version.
   13.12 + *
   13.13 + *   This program is distributed in the hope that it will be useful,
   13.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   13.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   13.16 + *   GNU General Public License for more details.
   13.17 + *
   13.18 + *   You should have received a copy of the GNU General Public License
   13.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   13.20 + */
   13.21 +
   13.22 +package com.so.news.command;
   13.23 +
   13.24 +import com.so.news.NNTPConnection;
   13.25 +import com.so.news.storage.Group;
   13.26 +
   13.27 +/**
   13.28 + * Class handling the GROUP command.
   13.29 + * @author Christian Lins
   13.30 + * @author Dennis Schwerdel
   13.31 + */
   13.32 +public class GroupCommand extends Command
   13.33 +{
   13.34 +  public GroupCommand(NNTPConnection conn)
   13.35 +  {
   13.36 +    super(conn);
   13.37 +  }
   13.38 +
   13.39 +  public boolean process(String[] command) 
   13.40 +    throws Exception
   13.41 +  {
   13.42 +    // untested, RFC977 compliant
   13.43 +    Group g = null;
   13.44 +    if (command.length >= 2)
   13.45 +    {
   13.46 +      g = Group.getByName(command[1]);
   13.47 +    }
   13.48 +    if (g == null)
   13.49 +    {
   13.50 +      printStatus(411, "no such news group");
   13.51 +      return true;
   13.52 +    }
   13.53 +    else
   13.54 +    {
   13.55 +      setCurrentGroup(g);
   13.56 +
   13.57 +      printStatus(211, g.getEstimatedArticleCount() + " " + g.getFirstArticle()
   13.58 +          + " " + g.getLastArticle() + " " + g.getName() + " group selected");
   13.59 +      return true;
   13.60 +    }
   13.61 +  }
   13.62 +
   13.63 +}
    14.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    14.2 +++ b/trunk/com/so/news/command/ListCommand.java	Tue Jan 20 10:21:03 2009 +0100
    14.3 @@ -0,0 +1,92 @@
    14.4 +/*
    14.5 + *   StarOffice News Server
    14.6 + *   see AUTHORS for the list of contributors
    14.7 + *
    14.8 + *   This program is free software: you can redistribute it and/or modify
    14.9 + *   it under the terms of the GNU General Public License as published by
   14.10 + *   the Free Software Foundation, either version 3 of the License, or
   14.11 + *   (at your option) any later version.
   14.12 + *
   14.13 + *   This program is distributed in the hope that it will be useful,
   14.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   14.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   14.16 + *   GNU General Public License for more details.
   14.17 + *
   14.18 + *   You should have received a copy of the GNU General Public License
   14.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   14.20 + */
   14.21 +
   14.22 +package com.so.news.command;
   14.23 +
   14.24 +import java.io.IOException;
   14.25 +import java.util.ArrayList;
   14.26 +import com.so.news.NNTPConnection;
   14.27 +import com.so.news.storage.Group;
   14.28 +
   14.29 +/**
   14.30 + * Class handling the LIST command.
   14.31 + * @author Christian Lins
   14.32 + * @author Dennis Schwerdel
   14.33 + */
   14.34 +public class ListCommand extends Command
   14.35 +{
   14.36 +  public ListCommand(NNTPConnection conn)
   14.37 +  {
   14.38 +    super(conn);
   14.39 +  }
   14.40 +
   14.41 +  public boolean process(String[] command) 
   14.42 +    throws Exception
   14.43 +  {
   14.44 +    if (command.length >= 2)
   14.45 +    {
   14.46 +      if (command[1].equalsIgnoreCase("OVERVIEW.FMT"))
   14.47 +      {
   14.48 +        printStatus(215, "information follows");
   14.49 +        printText("Subject:\nFrom:\nDate:\nMessage-ID:\nReferences:\nBytes:\nLines:");
   14.50 +        return true;
   14.51 +      }
   14.52 +      if (command[1].equalsIgnoreCase("NEWSGROUPS"))
   14.53 +      {
   14.54 +        printStatus(215, "information follows");
   14.55 +        ArrayList<Group> list = Group.getAll();
   14.56 +        for (Group g : list)
   14.57 +        {
   14.58 +          printTextLine(g.getName() + "\t" + "-");
   14.59 +        }
   14.60 +        println(".");
   14.61 +        flush();
   14.62 +        return true;
   14.63 +      }
   14.64 +      if (command[1].equalsIgnoreCase("SUBSCRIPTIONS"))
   14.65 +      {
   14.66 +        printStatus(215, "information follows");
   14.67 +        println(".");
   14.68 +        flush();
   14.69 +        return true;
   14.70 +      }
   14.71 +      if (command[1].equalsIgnoreCase("EXTENSIONS"))
   14.72 +      {
   14.73 +        printStatus(202, "Supported NNTP extensions.");
   14.74 +        printTextLine("LISTGROUP");
   14.75 +        println(".");
   14.76 +        flush();
   14.77 +        return true;
   14.78 +      }
   14.79 +      return false;
   14.80 +    }
   14.81 +    printStatus(215, "list of newsgroups follows");
   14.82 +    for (Group g : Group.getAll())
   14.83 +    {
   14.84 +      //if(g.getEstimatedArticleCount() <= 0)
   14.85 +      //  continue;
   14.86 +      
   14.87 +      printTextLine(g.getName() + " " + g.getLastArticle() + " "
   14.88 +          + g.getFirstArticle() + " y");
   14.89 +    }
   14.90 +    println(".");
   14.91 +    flush();
   14.92 +    return true;
   14.93 +  }
   14.94 +
   14.95 +}
    15.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    15.2 +++ b/trunk/com/so/news/command/ListGroupCommand.java	Tue Jan 20 10:21:03 2009 +0100
    15.3 @@ -0,0 +1,71 @@
    15.4 +/*
    15.5 + *   StarOffice News Server
    15.6 + *   see AUTHORS for the list of contributors
    15.7 + *
    15.8 + *   This program is free software: you can redistribute it and/or modify
    15.9 + *   it under the terms of the GNU General Public License as published by
   15.10 + *   the Free Software Foundation, either version 3 of the License, or
   15.11 + *   (at your option) any later version.
   15.12 + *
   15.13 + *   This program is distributed in the hope that it will be useful,
   15.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   15.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   15.16 + *   GNU General Public License for more details.
   15.17 + *
   15.18 + *   You should have received a copy of the GNU General Public License
   15.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   15.20 + */
   15.21 +
   15.22 +package com.so.news.command;
   15.23 +
   15.24 +import java.util.List;
   15.25 +import com.so.news.NNTPConnection;
   15.26 +import com.so.news.storage.Article;
   15.27 +import com.so.news.storage.Group;
   15.28 +
   15.29 +/**
   15.30 + * Class handling the LISTGROUP command.
   15.31 + * @author Christian Lins
   15.32 + * @author Dennis Schwerdel
   15.33 + */
   15.34 +public class ListGroupCommand extends Command
   15.35 +{
   15.36 +  public ListGroupCommand(NNTPConnection conn)
   15.37 +  {
   15.38 +    super(conn);
   15.39 +  }
   15.40 +
   15.41 +  public boolean process(String[] command) 
   15.42 +    throws Exception
   15.43 +  {
   15.44 +    String commandName = command[0];
   15.45 +    if (!commandName.equalsIgnoreCase("LISTGROUP"))
   15.46 +      return false;
   15.47 +    // untested, RFC977 complient
   15.48 +    Group group = null;
   15.49 +    if (command.length >= 2)
   15.50 +    {
   15.51 +      group = Group.getByName(command[1]);
   15.52 +    }
   15.53 +    else
   15.54 +    {
   15.55 +      group = getCurrentGroup();
   15.56 +    }
   15.57 +    if (group == null)
   15.58 +    {
   15.59 +      printStatus(412, "Not currently in newsgroup");
   15.60 +      return true;
   15.61 +    }
   15.62 +    List<Article> list = group.getAllArticles();
   15.63 +    printStatus(211, "list of article numbers follow"); // argh, bad english in
   15.64 +    // RFC
   15.65 +    for (Article a : list)
   15.66 +    {
   15.67 +      printTextLine("" + a.getNumberInGroup());
   15.68 +    }
   15.69 +    println(".");
   15.70 +    flush();
   15.71 +    return true;
   15.72 +  }
   15.73 +
   15.74 +}
    16.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    16.2 +++ b/trunk/com/so/news/command/NewGroupsCommand.java	Tue Jan 20 10:21:03 2009 +0100
    16.3 @@ -0,0 +1,68 @@
    16.4 +/*
    16.5 + *   StarOffice News Server
    16.6 + *   see AUTHORS for the list of contributors
    16.7 + *
    16.8 + *   This program is free software: you can redistribute it and/or modify
    16.9 + *   it under the terms of the GNU General Public License as published by
   16.10 + *   the Free Software Foundation, either version 3 of the License, or
   16.11 + *   (at your option) any later version.
   16.12 + *
   16.13 + *   This program is distributed in the hope that it will be useful,
   16.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   16.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   16.16 + *   GNU General Public License for more details.
   16.17 + *
   16.18 + *   You should have received a copy of the GNU General Public License
   16.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   16.20 + */
   16.21 +
   16.22 +package com.so.news.command;
   16.23 +
   16.24 +import java.io.IOException;
   16.25 +import java.util.ArrayList;
   16.26 +import com.so.news.NNTPConnection;
   16.27 +import com.so.news.storage.Group;
   16.28 +
   16.29 +/**
   16.30 + * Class handling the NEWGROUPS command.
   16.31 + * @author Christian Lins
   16.32 + * @author Dennis Schwerdel
   16.33 + */
   16.34 +public class NewGroupsCommand extends Command
   16.35 +{
   16.36 +  public NewGroupsCommand(NNTPConnection conn)
   16.37 +  {
   16.38 +    super(conn);
   16.39 +  }
   16.40 +
   16.41 +  public boolean process(String[] command) throws IOException
   16.42 +  {
   16.43 +    String commandName = command[0];
   16.44 +    if (!commandName.equalsIgnoreCase("NEWGROUPS"))
   16.45 +      return false;
   16.46 +    if (command.length != 3)
   16.47 +      return false;
   16.48 +    // untested, not RFC977 complient
   16.49 +    try
   16.50 +    {
   16.51 +      // Timestamp date = new Timestamp ( new SimpleDateFormat ("yyMMdd
   16.52 +      // HHmmss").parse(command[1] + " " + command[2] ).getTime()) ;
   16.53 +      printStatus(231, "list of new newsgroups follows");
   16.54 +      ArrayList<Group> list = Group.getAll();// (date) ;
   16.55 +      for (Group g : list)
   16.56 +      {
   16.57 +        printTextLine(g.getName() + " " + g.getLastArticle() + " "
   16.58 +            + g.getFirstArticle() + " y");
   16.59 +      }
   16.60 +      println(".");
   16.61 +      flush();
   16.62 +      return true;
   16.63 +    }
   16.64 +    catch (Exception e)
   16.65 +    {
   16.66 +      printStatus(511, "listing failed - invalid date format");
   16.67 +      return true;
   16.68 +    }
   16.69 +  }
   16.70 +
   16.71 +}
    17.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    17.2 +++ b/trunk/com/so/news/command/NextCommand.java	Tue Jan 20 10:21:03 2009 +0100
    17.3 @@ -0,0 +1,82 @@
    17.4 +/*
    17.5 + *   StarOffice News Server
    17.6 + *   see AUTHORS for the list of contributors
    17.7 + *
    17.8 + *   This program is free software: you can redistribute it and/or modify
    17.9 + *   it under the terms of the GNU General Public License as published by
   17.10 + *   the Free Software Foundation, either version 3 of the License, or
   17.11 + *   (at your option) any later version.
   17.12 + *
   17.13 + *   This program is distributed in the hope that it will be useful,
   17.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   17.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   17.16 + *   GNU General Public License for more details.
   17.17 + *
   17.18 + *   You should have received a copy of the GNU General Public License
   17.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   17.20 + */
   17.21 +
   17.22 +package com.so.news.command;
   17.23 +
   17.24 +import java.io.IOException;
   17.25 +import com.so.news.NNTPConnection;
   17.26 +import com.so.news.storage.Article;
   17.27 +import com.so.news.storage.Group;
   17.28 +
   17.29 +/**
   17.30 + * Class handling the NEXT and LAST command.
   17.31 + * @author Christian Lins
   17.32 + * @author Dennis Schwerdel
   17.33 + */
   17.34 +public class NextCommand extends Command
   17.35 +{
   17.36 +  public NextCommand(NNTPConnection conn)
   17.37 +  {
   17.38 +    super(conn);
   17.39 +  }
   17.40 +
   17.41 +  public boolean process(String[] command) throws IOException
   17.42 +  {
   17.43 +    String commandName = command[0];
   17.44 +    if (!(commandName.equalsIgnoreCase("NEXT") || commandName
   17.45 +        .equalsIgnoreCase("LAST")))
   17.46 +      return false;
   17.47 +    // untested, RFC977 complient
   17.48 +    Article currA = getCurrentArticle();
   17.49 +    Group currG = getCurrentGroup();
   17.50 +    if (currA == null)
   17.51 +    {
   17.52 +      printStatus(420, "no current article has been selected");
   17.53 +      return true;
   17.54 +    }
   17.55 +    if (currG == null)
   17.56 +    {
   17.57 +      printStatus(412, "no newsgroup selected");
   17.58 +      return true;
   17.59 +    }
   17.60 +    Article article;
   17.61 +    if (commandName.equalsIgnoreCase("NEXT"))
   17.62 +    {
   17.63 +      article = currA.nextArticleInGroup();
   17.64 +      if (article == null)
   17.65 +      {
   17.66 +        printStatus(421, "no next article in this group");
   17.67 +        return true;
   17.68 +      }
   17.69 +    }
   17.70 +    else
   17.71 +    {
   17.72 +      article = currA.prevArticleInGroup();
   17.73 +      if (article == null)
   17.74 +      {
   17.75 +        printStatus(422, "no previous article in this group");
   17.76 +        return true;
   17.77 +      }
   17.78 +    }
   17.79 +    setCurrentArticle(article);
   17.80 +    printStatus(223, article.getNumberInGroup() + " " + article.getMessageID()
   17.81 +        + " article retrieved - request text separately");
   17.82 +    return true;
   17.83 +  }
   17.84 +
   17.85 +}
    18.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    18.2 +++ b/trunk/com/so/news/command/OverCommand.java	Tue Jan 20 10:21:03 2009 +0100
    18.3 @@ -0,0 +1,183 @@
    18.4 +/*
    18.5 + *   StarOffice News Server
    18.6 + *   see AUTHORS for the list of contributors
    18.7 + *
    18.8 + *   This program is free software: you can redistribute it and/or modify
    18.9 + *   it under the terms of the GNU General Public License as published by
   18.10 + *   the Free Software Foundation, either version 3 of the License, or
   18.11 + *   (at your option) any later version.
   18.12 + *
   18.13 + *   This program is distributed in the hope that it will be useful,
   18.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   18.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   18.16 + *   GNU General Public License for more details.
   18.17 + *
   18.18 + *   You should have received a copy of the GNU General Public License
   18.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   18.20 + */
   18.21 +
   18.22 +package com.so.news.command;
   18.23 +
   18.24 +import java.text.SimpleDateFormat;
   18.25 +import java.util.Locale;
   18.26 +
   18.27 +import com.so.news.Debug;
   18.28 +import com.so.news.NNTPConnection;
   18.29 +import com.so.news.storage.Article;
   18.30 +
   18.31 +/**
   18.32 + * Class handling the OVER/XOVER command.
   18.33 + * 
   18.34 + * Description of the XOVER command:
   18.35 + * 
   18.36 + * XOVER [range]
   18.37 + *
   18.38 + * The XOVER command returns information from the overview
   18.39 + * database for the article(s) specified.
   18.40 + *
   18.41 + * The optional range argument may be any of the following:
   18.42 + *              an article number
   18.43 + *              an article number followed by a dash to indicate
   18.44 + *                 all following
   18.45 + *              an article number followed by a dash followed by
   18.46 + *                 another article number
   18.47 + *
   18.48 + * If no argument is specified, then information from the
   18.49 + * current article is displayed. Successful responses start
   18.50 + * with a 224 response followed by the overview information
   18.51 + * for all matched messages. Once the output is complete, a
   18.52 + * period is sent on a line by itself. If no argument is
   18.53 + * specified, the information for the current article is
   18.54 + * returned.  A news group must have been selected earlier,
   18.55 + * else a 412 error response is returned. If no articles are
   18.56 + * in the range specified, a 420 error response is returned
   18.57 + * by the server. A 502 response will be returned if the
   18.58 + * client only has permission to transfer articles.
   18.59 + *
   18.60 + * Each line of output will be formatted with the article number,
   18.61 + * followed by each of the headers in the overview database or the
   18.62 + * article itself (when the data is not available in the overview
   18.63 + * database) for that article separated by a tab character.  The
   18.64 + * sequence of fields must be in this order: subject, author,
   18.65 + * date, message-id, references, byte count, and line count. Other
   18.66 + * optional fields may follow line count. Other optional fields may
   18.67 + * follow line count. These fields are specified by examining the
   18.68 + * response to the LIST OVERVIEW.FMT command. Where no data exists,
   18.69 + * a null field must be provided (i.e. the output will have two tab
   18.70 + * characters adjacent to each other). Servers should not output
   18.71 + * fields for articles that have been removed since the XOVER database
   18.72 + * was created.
   18.73 + *
   18.74 + * The LIST OVERVIEW.FMT command should be implemented if XOVER
   18.75 + * is implemented. A client can use LIST OVERVIEW.FMT to determine
   18.76 + * what optional fields  and in which order all fields will be
   18.77 + * supplied by the XOVER command. 
   18.78 + *
   18.79 + * Note that any tab and end-of-line characters in any header
   18.80 + * data that is returned will be converted to a space character.
   18.81 + *
   18.82 + * Responses:
   18.83 + *
   18.84 + *   224 Overview information follows
   18.85 + *   412 No news group current selected
   18.86 + *   420 No article(s) selected
   18.87 + *   502 no permission
   18.88 + * 
   18.89 + * @author Christian Lins
   18.90 + */
   18.91 +public class OverCommand extends Command
   18.92 +{
   18.93 +  public OverCommand(NNTPConnection conn)
   18.94 +  {
   18.95 +    super(conn);
   18.96 +  }
   18.97 +  
   18.98 +  public boolean process(String[] command)
   18.99 +    throws Exception
  18.100 +  {
  18.101 +    if(getCurrentGroup() == null)
  18.102 +    {
  18.103 +      printStatus(412, "No news group current selected");
  18.104 +      return false;
  18.105 +    }
  18.106 +    
  18.107 +    // If no parameter was specified, show information about
  18.108 +    // the currently selected article(s)
  18.109 +    if(command.length == 1)
  18.110 +    {
  18.111 +      Article art = getCurrentArticle();
  18.112 +      if(art == null)
  18.113 +      {
  18.114 +        printStatus(420, "No article(s) selected");
  18.115 +        return false;
  18.116 +      }
  18.117 +      
  18.118 +      String o = buildOverview(art, -1);
  18.119 +      printText(o);
  18.120 +    }
  18.121 +    // otherwise print information about the specified range
  18.122 +    else
  18.123 +    {
  18.124 +      int artStart = -1;
  18.125 +      int artEnd   = -1;
  18.126 +      String[] nums = command[1].split("-");
  18.127 +      if(nums.length > 1)
  18.128 +      {
  18.129 +        try
  18.130 +        {
  18.131 +          artStart = Integer.parseInt(nums[0]);
  18.132 +        }
  18.133 +        catch(Exception e) 
  18.134 +        {
  18.135 +          artStart = Integer.parseInt(command[1]);
  18.136 +        }
  18.137 +        try
  18.138 +        {
  18.139 +          artEnd = Integer.parseInt(nums[1]);
  18.140 +        }
  18.141 +        catch(Exception e) {}
  18.142 +      }
  18.143 +
  18.144 +      printStatus(224, "Overview information follows");
  18.145 +      for(int n = artStart; n <= artEnd; n++)
  18.146 +      {
  18.147 +        Article art = Article.getByNumberInGroup(getCurrentGroup(), n);
  18.148 +        if(art == null)
  18.149 +        {
  18.150 +          Debug.getInstance().log("Article (gid=" + getCurrentGroup() + ", art=" + n + " is null!");
  18.151 +        }
  18.152 +        else
  18.153 +        {
  18.154 +          printTextPart(buildOverview(art, n) + NEWLINE);
  18.155 +        }
  18.156 +      }
  18.157 +      println(".");
  18.158 +      flush();
  18.159 +    }
  18.160 +    
  18.161 +    return true;
  18.162 +  }
  18.163 +  
  18.164 +  private String buildOverview(Article art, int nr)
  18.165 +  {
  18.166 +    SimpleDateFormat sdf = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss Z", Locale.US);
  18.167 +    StringBuilder overview = new StringBuilder();
  18.168 +    overview.append(nr);
  18.169 +    overview.append('\t');
  18.170 +    overview.append(art.getHeader().get("Subject"));
  18.171 +    overview.append('\t');
  18.172 +    overview.append(art.getHeader().get("From"));
  18.173 +    overview.append('\t');
  18.174 +    overview.append(sdf.format(art.getDate()));
  18.175 +    overview.append('\t');
  18.176 +    overview.append(art.getHeader().get("Message-ID"));
  18.177 +    overview.append('\t');
  18.178 +    overview.append(art.getHeader().get("References"));
  18.179 +    overview.append('\t');
  18.180 +    overview.append(art.getHeader().get("Bytes"));
  18.181 +    overview.append('\t');
  18.182 +    overview.append(art.getHeader().get("Lines"));
  18.183 +    
  18.184 +    return overview.toString();
  18.185 +  }
  18.186 +}
    19.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    19.2 +++ b/trunk/com/so/news/command/PostCommand.java	Tue Jan 20 10:21:03 2009 +0100
    19.3 @@ -0,0 +1,166 @@
    19.4 +/*
    19.5 + *   StarOffice News Server
    19.6 + *   see AUTHORS for the list of contributors
    19.7 + *
    19.8 + *   This program is free software: you can redistribute it and/or modify
    19.9 + *   it under the terms of the GNU General Public License as published by
   19.10 + *   the Free Software Foundation, either version 3 of the License, or
   19.11 + *   (at your option) any later version.
   19.12 + *
   19.13 + *   This program is distributed in the hope that it will be useful,
   19.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   19.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   19.16 + *   GNU General Public License for more details.
   19.17 + *
   19.18 + *   You should have received a copy of the GNU General Public License
   19.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   19.20 + */
   19.21 +
   19.22 +package com.so.news.command;
   19.23 +
   19.24 +import java.io.IOException;
   19.25 +import java.sql.SQLException;
   19.26 +import java.util.Date;
   19.27 +import java.text.SimpleDateFormat;
   19.28 +import java.util.HashMap;
   19.29 +import java.util.Locale;
   19.30 +
   19.31 +import com.so.news.Config;
   19.32 +import com.so.news.Debug;
   19.33 +import com.so.news.NNTPConnection;
   19.34 +import com.so.news.storage.Article;
   19.35 +import com.so.news.storage.Database;
   19.36 +
   19.37 +/**
   19.38 + * Contains the code for the POST command.
   19.39 + * @author Christian Lins
   19.40 + * @author Dennis Schwerdel
   19.41 + */
   19.42 +public class PostCommand extends Command
   19.43 +{
   19.44 +  public PostCommand(NNTPConnection conn)
   19.45 +  {
   19.46 +    super(conn);
   19.47 +  }
   19.48 +
   19.49 +  public boolean process(String[] command) throws IOException
   19.50 +  {
   19.51 +    printStatus(340, "send article to be posted. End with <CR-LF>.<CR-LF>");
   19.52 +
   19.53 +    // some initialization
   19.54 +    Article article = new Article();
   19.55 +    int lineCount     = 0;
   19.56 +    long bodySize     = 0;
   19.57 +    long maxBodySize  = Config.getInstance().get("n3tpd.article.maxsize", 1024) * 1024; // Size in bytes
   19.58 +
   19.59 +    // begin with a stringbuilder body
   19.60 +    StringBuilder body = new StringBuilder();
   19.61 +    HashMap<String, String> header = new HashMap<String, String>();
   19.62 +
   19.63 +    boolean isHeader = true; // are we in the header part
   19.64 +
   19.65 +    String line = readTextLine();
   19.66 +    while(line != null)
   19.67 +    {
   19.68 +      bodySize += line.length();
   19.69 +      if(bodySize > maxBodySize)
   19.70 +      {
   19.71 +        printStatus(500, "article is too long");
   19.72 +        return false;
   19.73 +      }
   19.74 +
   19.75 +      if(!isHeader)
   19.76 +      { // body
   19.77 +        if(line.trim().equals("."))
   19.78 +          break;
   19.79 +        
   19.80 +        bodySize += line.length() + 1;
   19.81 +        lineCount++;
   19.82 +        body.append(line + NEWLINE);
   19.83 +      }
   19.84 +      
   19.85 +      if(line.equals(""))
   19.86 +      {
   19.87 +        isHeader = false; // we finally met the blank line
   19.88 +                          // separating headers from body
   19.89 +      }
   19.90 +
   19.91 +      if(isHeader)
   19.92 +      { // header
   19.93 +        // split name and value and add the header to the map
   19.94 +        int colon = line.indexOf(':');
   19.95 +        String fieldName = line.substring(0, colon).trim();
   19.96 +        String fieldValue = line.substring(colon + 1).trim();
   19.97 +        header.put(fieldName, fieldValue);
   19.98 +      }
   19.99 +      line = readTextLine(); // read a new line
  19.100 +    } // end of input reading
  19.101 +
  19.102 +    article.setBody(body.toString()); // set the article body
  19.103 +    article.setHeader(header);     // add the header entries for the article
  19.104 +    
  19.105 +    // Read the date header and fall back to the current date if it is not set
  19.106 +    try
  19.107 +    {
  19.108 +      SimpleDateFormat sdf = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss Z", Locale.US);
  19.109 +      String date = header.get("DATE");
  19.110 +      if(date == null)
  19.111 +        article.setDate(new Date());
  19.112 +      else
  19.113 +        article.setDate(new Date(sdf.parse(date).getTime())) ;
  19.114 +    }
  19.115 +    catch (Exception e)
  19.116 +    {
  19.117 +      e.printStackTrace(Debug.getInstance().getStream());
  19.118 +      printStatus(541, "posting failed - invalid date format");
  19.119 +      return true;
  19.120 +    }
  19.121 +
  19.122 +    // check for a cancel command
  19.123 +    if ( header.containsKey("Control") ) 
  19.124 +    {
  19.125 +      String[] control = header.get("Control").split(" ") ;
  19.126 +      if ( control.length >= 2 && control[0].equalsIgnoreCase("cancel") ) 
  19.127 +      {
  19.128 +        // this article is a cancel-article, try to delete the old article
  19.129 +        try
  19.130 +        {
  19.131 +          Article.getByMessageID(control[1]).delete();
  19.132 +          printStatus(240, "article posted ok - original article canceled"); // quite
  19.133 +          return true; // quit, do not actually post this article since it
  19.134 +        }
  19.135 +        catch (Exception e)
  19.136 +        {
  19.137 +          e.printStackTrace();
  19.138 +          printStatus(441, "posting failed - original posting not found");
  19.139 +          return true;
  19.140 +        }
  19.141 +      }
  19.142 +    }
  19.143 +
  19.144 +    // set some headers
  19.145 +    header.put("Message-ID", article.getMessageID());
  19.146 +    header.put("Lines", "" + lineCount);
  19.147 +    header.put("Bytes", "" + bodySize);
  19.148 +
  19.149 +    // if needed, set an empty references header, that means this is
  19.150 +    // a initial posting
  19.151 +    if (!header.containsKey("References"))
  19.152 +      header.put("References", "");
  19.153 +
  19.154 +    // try to create the article in the database
  19.155 +    try
  19.156 +    {
  19.157 +      Database.getInstance().addArticle(article);
  19.158 +      printStatus(240, "article posted ok");
  19.159 +    }
  19.160 +    catch(SQLException ex)
  19.161 +    {
  19.162 +      System.err.println(ex.getLocalizedMessage());
  19.163 +      ex.printStackTrace(Debug.getInstance().getStream());
  19.164 +      printStatus(500, "internal server error");
  19.165 +    }
  19.166 +
  19.167 +    return true;
  19.168 +  }
  19.169 +}
    20.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    20.2 +++ b/trunk/com/so/news/io/Resource.java	Tue Jan 20 10:21:03 2009 +0100
    20.3 @@ -0,0 +1,123 @@
    20.4 +/*
    20.5 + *   StarOffice News Server
    20.6 + *   see AUTHORS for the list of contributors
    20.7 + *
    20.8 + *   This program is free software: you can redistribute it and/or modify
    20.9 + *   it under the terms of the GNU General Public License as published by
   20.10 + *   the Free Software Foundation, either version 3 of the License, or
   20.11 + *   (at your option) any later version.
   20.12 + *
   20.13 + *   This program is distributed in the hope that it will be useful,
   20.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   20.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   20.16 + *   GNU General Public License for more details.
   20.17 + *
   20.18 + *   You should have received a copy of the GNU General Public License
   20.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   20.20 + */
   20.21 +
   20.22 +package com.so.news.io;
   20.23 +
   20.24 +import java.io.BufferedReader;
   20.25 +import java.io.File;
   20.26 +import java.io.FileInputStream;
   20.27 +import java.io.IOException;
   20.28 +import java.io.InputStream;
   20.29 +import java.io.InputStreamReader;
   20.30 +import java.net.URL;
   20.31 +import java.nio.charset.Charset;
   20.32 +
   20.33 +/**
   20.34 + * Provides method for loading of resources.
   20.35 + * @author Christian Lins
   20.36 + */
   20.37 +public class Resource
   20.38 +{
   20.39 +  /**
   20.40 +   * Loads a file as array of byte. As the file is completely loaded into
   20.41 +   * memory this method should only be used with small files.
   20.42 +   * @param file
   20.43 +   * @return
   20.44 +   */
   20.45 +  public static byte[] getBytes(File file)
   20.46 +  {
   20.47 +    try
   20.48 +    {
   20.49 +      FileInputStream in = new FileInputStream(file);
   20.50 +      byte[] buffer = new byte[(int)file.length()];
   20.51 +      
   20.52 +      in.read(buffer);
   20.53 +      
   20.54 +      return buffer;
   20.55 +    }
   20.56 +    catch(IOException ex)
   20.57 +    {
   20.58 +      System.err.println(ex.getLocalizedMessage());
   20.59 +      return null;
   20.60 +    }
   20.61 +  }
   20.62 +  
   20.63 +  /**
   20.64 +   * Loads a resource and returns it as URL reference.
   20.65 +   * The Resource's classloader is used to load the resource, not
   20.66 +   * the System's ClassLoader so it may be safe to use this method
   20.67 +   * in a sandboxed environment.
   20.68 +   * @return
   20.69 +   */
   20.70 +  public static URL getAsURL(String name)
   20.71 +  {
   20.72 +    return Resource.class.getClassLoader().getResource(name);
   20.73 +  }
   20.74 +  
   20.75 +  /**
   20.76 +   * Loads a resource and returns an InputStream to it.
   20.77 +   * @param name
   20.78 +   * @return
   20.79 +   */
   20.80 +  public static InputStream getAsStream(String name)
   20.81 +  {
   20.82 +    try
   20.83 +    {
   20.84 +      URL url = getAsURL(name);
   20.85 +      return url.openStream();
   20.86 +    }
   20.87 +    catch(IOException e)
   20.88 +    {
   20.89 +      e.printStackTrace();
   20.90 +      return null;
   20.91 +    }
   20.92 +  }
   20.93 +
   20.94 +  /**
   20.95 +   * Loads a plain text resource.
   20.96 +   * @param withNewline If false all newlines are removed from the 
   20.97 +   * return String
   20.98 +   */
   20.99 +  public static String getAsString(String name, boolean withNewline)
  20.100 +  {
  20.101 +    try
  20.102 +    {
  20.103 +      BufferedReader in  = new BufferedReader(
  20.104 +          new InputStreamReader(getAsStream(name), Charset.forName("UTF-8")));
  20.105 +      StringBuffer   buf = new StringBuffer();
  20.106 +
  20.107 +      for(;;)
  20.108 +      {
  20.109 +        String line = in.readLine();
  20.110 +        if(line == null)
  20.111 +          break;
  20.112 +
  20.113 +        buf.append(line);
  20.114 +        if(withNewline)
  20.115 +          buf.append('\n');
  20.116 +      }
  20.117 +
  20.118 +      return buf.toString();
  20.119 +    }
  20.120 +    catch(Exception e)
  20.121 +    {
  20.122 +      e.printStackTrace();
  20.123 +      return null;
  20.124 +    }
  20.125 +  }
  20.126 +}
    21.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    21.2 +++ b/trunk/com/so/news/storage/Article.java	Tue Jan 20 10:21:03 2009 +0100
    21.3 @@ -0,0 +1,307 @@
    21.4 +/*
    21.5 + *   StarOffice News Server
    21.6 + *   see AUTHORS for the list of contributors
    21.7 + *
    21.8 + *   This program is free software: you can redistribute it and/or modify
    21.9 + *   it under the terms of the GNU General Public License as published by
   21.10 + *   the Free Software Foundation, either version 3 of the License, or
   21.11 + *   (at your option) any later version.
   21.12 + *
   21.13 + *   This program is distributed in the hope that it will be useful,
   21.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   21.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   21.16 + *   GNU General Public License for more details.
   21.17 + *
   21.18 + *   You should have received a copy of the GNU General Public License
   21.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   21.20 + */
   21.21 +
   21.22 +package com.so.news.storage;
   21.23 +
   21.24 +import java.sql.ResultSet;
   21.25 +import java.sql.SQLException;
   21.26 +import java.util.Date;
   21.27 +import java.util.HashMap;
   21.28 +import java.util.Map;
   21.29 +import java.util.Map.Entry;
   21.30 +import java.util.UUID;
   21.31 +
   21.32 +import com.so.news.Config;
   21.33 +import com.so.news.Debug;
   21.34 +
   21.35 +/**
   21.36 + * Represents a newsgroup article.
   21.37 + * @author Christian Lins
   21.38 + * @author Denis Schwerdel
   21.39 + */
   21.40 +public class Article
   21.41 +{
   21.42 +  /**
   21.43 +   * Loads the Article identified by the given ID from the Database.
   21.44 +   * @param messageID
   21.45 +   * @return null if Article is not found or if an error occurred.
   21.46 +   */
   21.47 +  public static Article getByMessageID(String messageID)
   21.48 +  {
   21.49 +    try
   21.50 +    {
   21.51 +      return Database.getInstance().getArticle(messageID);
   21.52 +    }
   21.53 +    catch(SQLException ex)
   21.54 +    {
   21.55 +      ex.printStackTrace(Debug.getInstance().getStream());
   21.56 +      return null;
   21.57 +    }
   21.58 +  }
   21.59 +  
   21.60 +  public static Article getByNumberInGroup(Group group, int number)
   21.61 +    throws SQLException
   21.62 +  {
   21.63 +    long gid = group.getID(); 
   21.64 +    return Database.getInstance().getArticle(gid, number); // Is number her correct?
   21.65 +  }
   21.66 +  
   21.67 +  private String              body      = "";
   21.68 +  private long                groupID   = -1;
   21.69 +  private Map<String, String> header    = new HashMap<String, String>();
   21.70 +  private int                 numberInGroup = -1;
   21.71 +  private String              msgID     = null;
   21.72 +  
   21.73 +  /**
   21.74 +   * Default constructor.
   21.75 +   */
   21.76 +  public Article()
   21.77 +  {
   21.78 +  }
   21.79 +  
   21.80 +  /**
   21.81 +   * Creates a new Article object using the date from the given
   21.82 +   * ResultSet. It is expected that ResultSet.next() was already
   21.83 +   * called by the Database class.
   21.84 +   * This construction has only package visibility.
   21.85 +   * @param rs
   21.86 +   */
   21.87 +  Article(ResultSet rs)
   21.88 +    throws SQLException
   21.89 +  {
   21.90 +    this.body  = rs.getString("body");
   21.91 +    this.msgID = rs.getString("message_id");
   21.92 +    
   21.93 +    // Parse the header
   21.94 +    parseHeader(rs.getString("header"));
   21.95 +  }
   21.96 +  
   21.97 +  /**
   21.98 +   * Parses the header fields and puts them into a map for faster access.
   21.99 +   * TODO: There could be fields that go over more than one line, some
  21.100 +   * bad clients do create them.
  21.101 +   * @param hsrc
  21.102 +   */
  21.103 +  private void parseHeader(String hsrc)
  21.104 +  {
  21.105 +    String[] lines = hsrc.split("\n");
  21.106 +    
  21.107 +    for(String line : lines)
  21.108 +    {
  21.109 +      String[] kv = line.split(":");
  21.110 +      if(kv.length < 2)
  21.111 +      {
  21.112 +        Debug.getInstance().log("Invalid header field: " + line);
  21.113 +        continue;
  21.114 +      }
  21.115 +      else
  21.116 +      {
  21.117 +        // Set value in the header hash map
  21.118 +        String value = kv[1];
  21.119 +        for(int n = 2; n < kv.length; n++)
  21.120 +          value += ":" + kv[n];
  21.121 +        this.header.put(kv[0], value);
  21.122 +      }
  21.123 +    }
  21.124 +  }
  21.125 +  
  21.126 +  /**
  21.127 +   * Returnes the next Article in the group of this Article.
  21.128 +   * @return
  21.129 +   */
  21.130 +  public Article nextArticleInGroup()
  21.131 +  {
  21.132 +    return null;
  21.133 +  }
  21.134 +
  21.135 +  /**
  21.136 +   * Returns the previous Article in the group of this Article.
  21.137 +   * @return
  21.138 +   */
  21.139 +  public Article prevArticleInGroup()
  21.140 +  {
  21.141 +    return null;
  21.142 +  }
  21.143 +
  21.144 +  /**
  21.145 +   * Generates a message id for this article and sets it into
  21.146 +   * the header HashMap.
  21.147 +   */
  21.148 +  private String generateMessageID()
  21.149 +  {
  21.150 +    this.msgID = "<" + UUID.randomUUID() + "@"
  21.151 +        + Config.getInstance().get("n3tpd.hostname", "localhost") + ">";
  21.152 +    
  21.153 +    this.header.put("Message-ID", msgID);
  21.154 +    
  21.155 +    return msgID;
  21.156 +  }
  21.157 +
  21.158 +  /**
  21.159 +   * Tries to delete this article.
  21.160 +   * @return false if the article could not be deleted, otherwise true
  21.161 +   */
  21.162 +  public boolean delete()
  21.163 +  {
  21.164 +    return false;
  21.165 +  }
  21.166 +  
  21.167 +  /**
  21.168 +   * Checks if all necessary header fields are within this header.
  21.169 +   */
  21.170 +  private void validateHeader()
  21.171 +  {    
  21.172 +    // Forces a MessageID creation if not existing
  21.173 +    getMessageID();
  21.174 +    
  21.175 +    // Check if the references are correct...
  21.176 +    String rep = header.get("In-Reply-To");
  21.177 +    if(rep == null) // Some clients use only references instead of In-Reply-To
  21.178 +      return; //rep = header.get("References");
  21.179 +    
  21.180 +    String ref = getMessageID();
  21.181 +    
  21.182 +    if(rep != null && !rep.equals(""))
  21.183 +    {
  21.184 +      Article art = null; //TODO // getByMessageID(rep, articleDir);
  21.185 +      if(art != null)
  21.186 +      {
  21.187 +        ref = art.header.get("References") + " " + rep;
  21.188 +      }
  21.189 +    }
  21.190 +    header.put("References", ref);
  21.191 +  }
  21.192 +
  21.193 +  /**
  21.194 +   * Returns the body string.
  21.195 +   */
  21.196 +  public String getBody()
  21.197 +  {
  21.198 +    return body;
  21.199 +  }
  21.200 +  
  21.201 +  /**
  21.202 +   * @return Numerical ID of the associated Group.
  21.203 +   */
  21.204 +  long getGroupID()
  21.205 +  {
  21.206 +    if(groupID == -1) // If the GroupID was not determined yet
  21.207 +    {
  21.208 +      // Determining GroupID
  21.209 +      String   newsgroups = this.header.get("Newsgroups");
  21.210 +      if(newsgroups != null)
  21.211 +      {
  21.212 +        String[] newsgroup  = newsgroups.split(",");
  21.213 +        // Crossposting is not supported
  21.214 +        try
  21.215 +        {
  21.216 +          Group group;
  21.217 +          if(newsgroup.length > 0)
  21.218 +            group = Database.getInstance().getGroup(newsgroup[0].trim());
  21.219 +          else
  21.220 +            group = Database.getInstance().getGroup(newsgroups.trim());
  21.221 +          // TODO: What to do if Group does not exist?
  21.222 +          this.groupID = group.getID();
  21.223 +        }
  21.224 +        catch(SQLException ex)
  21.225 +        {
  21.226 +          ex.printStackTrace(Debug.getInstance().getStream());
  21.227 +          System.err.println(ex.getLocalizedMessage());
  21.228 +        }
  21.229 +      }
  21.230 +      else
  21.231 +        System.err.println("Should never happen: Article::getGroupID");
  21.232 +    }
  21.233 +    return this.groupID;
  21.234 +  }
  21.235 +
  21.236 +  public void setBody(String body)
  21.237 +  {
  21.238 +    this.body = body;
  21.239 +  }
  21.240 +
  21.241 +  public int getNumberInGroup()
  21.242 +  {
  21.243 +    return this.numberInGroup;
  21.244 +  }
  21.245 +  
  21.246 +  public void setHeader(HashMap<String, String> header)
  21.247 +  {
  21.248 +    this.header = header;
  21.249 +  }
  21.250 +
  21.251 +  public void setNumberInGroup(int id)
  21.252 +  {
  21.253 +    this.numberInGroup = id;
  21.254 +  }
  21.255 +
  21.256 +  public String getMessageID()
  21.257 +  {
  21.258 +    if(msgID == null)
  21.259 +      msgID = generateMessageID();
  21.260 +    return msgID;
  21.261 +  }
  21.262 +
  21.263 +  /**
  21.264 +   * @return Header source code of this Article.
  21.265 +   */
  21.266 +  public String getHeaderSource()
  21.267 +  {
  21.268 +    StringBuffer buf = new StringBuffer();
  21.269 +    
  21.270 +    for(Entry<String, String> entry : this.header.entrySet())
  21.271 +    {
  21.272 +      buf.append(entry.getKey());
  21.273 +      buf.append(":");
  21.274 +      buf.append(entry.getValue());
  21.275 +      buf.append("\n");
  21.276 +    }
  21.277 +    
  21.278 +    return buf.toString();
  21.279 +  }
  21.280 +  
  21.281 +  public Map<String, String> getHeader()
  21.282 +  {
  21.283 +    return this.header;
  21.284 +  }
  21.285 +  
  21.286 +  public Date getDate()
  21.287 +  {
  21.288 +    try
  21.289 +    {
  21.290 +      String date = this.header.get("Date");
  21.291 +      return new Date(Date.parse(date));
  21.292 +    }
  21.293 +    catch(Exception e)
  21.294 +    {
  21.295 +      e.printStackTrace(Debug.getInstance().getStream());
  21.296 +      return null;
  21.297 +    }
  21.298 +  }
  21.299 +
  21.300 +  public void setDate(Date date)
  21.301 +  {
  21.302 +    this.header.put("Date", date.toString());
  21.303 +  }
  21.304 +  
  21.305 +  @Override
  21.306 +  public String toString()
  21.307 +  {
  21.308 +    return getMessageID();
  21.309 +  }
  21.310 +}
    22.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    22.2 +++ b/trunk/com/so/news/storage/Database.java	Tue Jan 20 10:21:03 2009 +0100
    22.3 @@ -0,0 +1,327 @@
    22.4 +/*
    22.5 + *   StarOffice News Server
    22.6 + *   see AUTHORS for the list of contributors
    22.7 + *
    22.8 + *   This program is free software: you can redistribute it and/or modify
    22.9 + *   it under the terms of the GNU General Public License as published by
   22.10 + *   the Free Software Foundation, either version 3 of the License, or
   22.11 + *   (at your option) any later version.
   22.12 + *
   22.13 + *   This program is distributed in the hope that it will be useful,
   22.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   22.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   22.16 + *   GNU General Public License for more details.
   22.17 + *
   22.18 + *   You should have received a copy of the GNU General Public License
   22.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   22.20 + */
   22.21 +
   22.22 +package com.so.news.storage;
   22.23 +
   22.24 +import java.sql.Connection;
   22.25 +import java.sql.DriverManager;
   22.26 +import java.sql.ResultSet;
   22.27 +import java.sql.SQLException;
   22.28 +import java.sql.Statement;
   22.29 +
   22.30 +import java.util.zip.CRC32;
   22.31 +import com.so.news.Config;
   22.32 +import com.so.news.util.StringTemplate;
   22.33 +
   22.34 +/**
   22.35 + * Database abstraction class.
   22.36 + * @author Christian Lins (christian.lins@web.de)
   22.37 + */
   22.38 +public class Database
   22.39 +{
   22.40 +  private static Database instance = null;
   22.41 +  
   22.42 +  /**
   22.43 +   * Initializes the Database subsystem, e.g. loading a JDBC driver and
   22.44 +   * connection to the Database Managment System.
   22.45 +   * This method is called when the daemon starts up or at the first
   22.46 +   * call to Database.getInstance().
   22.47 +   * @throws java.lang.Exception
   22.48 +   */
   22.49 +  public static void arise()
   22.50 +    throws Exception
   22.51 +  {
   22.52 +    // Tries to load the Database driver and establish a connection.
   22.53 +    if(instance == null)
   22.54 +      instance = new Database();
   22.55 +  }
   22.56 +  
   22.57 +  /**
   22.58 +   * @return Instance of the current Database backend. Returns null if an error
   22.59 +   * has occurred.
   22.60 +   */
   22.61 +  public static Database getInstance()
   22.62 +  {
   22.63 +    try
   22.64 +    {
   22.65 +      arise();
   22.66 +      return instance;
   22.67 +    }
   22.68 +    catch(Exception ex)
   22.69 +    {
   22.70 +      ex.printStackTrace();
   22.71 +      return null;
   22.72 +    }
   22.73 +  }
   22.74 +  
   22.75 +  private Connection conn = null;
   22.76 +  
   22.77 +  /**
   22.78 +   * Private constructor.
   22.79 +   * @throws java.lang.Exception
   22.80 +   */
   22.81 +  private Database()
   22.82 +    throws Exception
   22.83 +  {
   22.84 +    Class.forName(
   22.85 +            Config.getInstance().get("n3tpd.storage.dbmsdriver", ""));
   22.86 +    this.conn = DriverManager.getConnection(
   22.87 +            Config.getInstance().get("n3tpd.storage.database", ""),
   22.88 +            Config.getInstance().get("n3tpd.storage.user", "n3tpd_user"),
   22.89 +            Config.getInstance().get("n3tpd.storage.password", ""));
   22.90 +    this.conn.setAutoCommit(false);
   22.91 +  }
   22.92 +  
   22.93 +  /**
   22.94 +   * Adds an article to the database.
   22.95 +   * @param article
   22.96 +   * @return
   22.97 +   * @throws java.sql.SQLException
   22.98 +   */
   22.99 +  public boolean addArticle(Article article)
  22.100 +    throws SQLException
  22.101 +  {
  22.102 +    Statement stmt = this.conn.createStatement();
  22.103 +
  22.104 +    String sql0 = "START TRANSACTION";
  22.105 +    String sql1 = "INSERT INTO articles (message_id,header,body)" +
  22.106 +            "VALUES('%mid', '%header', '%body')";
  22.107 +    StringTemplate tmpl = new StringTemplate(sql1);
  22.108 +    tmpl.set("body", article.getBody());
  22.109 +    tmpl.set("mid", article.getMessageID());
  22.110 +    tmpl.set("header", article.getHeaderSource());
  22.111 +    sql1 = tmpl.toString();
  22.112 +    
  22.113 +    String sql2 = "COMMIT";
  22.114 +    
  22.115 +    // Add statements as batch
  22.116 +    stmt.addBatch(sql0);
  22.117 +    stmt.addBatch(sql1);
  22.118 +    
  22.119 +    // TODO: For each newsgroup add a reference
  22.120 +    String sql = "INSERT INTO postings (group_id, article_id, article_index)" +
  22.121 +                 "VALUES (%gid, (SELECT article_id FROM articles WHERE message_id = '%mid')," +
  22.122 +                 " %idx)";
  22.123 +    
  22.124 +    tmpl = new StringTemplate(sql);
  22.125 +    tmpl.set("gid", article.getGroupID());
  22.126 +    tmpl.set("mid", article.getMessageID());
  22.127 +    tmpl.set("idx", getMaxArticleIndex() + 1);
  22.128 +    stmt.addBatch(tmpl.toString());
  22.129 +    
  22.130 +    // Commit
  22.131 +    stmt.addBatch(sql2);
  22.132 +    
  22.133 +    // And execute the batch
  22.134 +    stmt.executeBatch();
  22.135 +    
  22.136 +    return true;
  22.137 +  }
  22.138 +  
  22.139 +  /**
  22.140 +   * Adds a group to the Database.
  22.141 +   * @param name
  22.142 +   * @throws java.sql.SQLException
  22.143 +   */
  22.144 +  public boolean addGroup(String name)
  22.145 +    throws SQLException
  22.146 +  {
  22.147 +    CRC32 crc = new CRC32();
  22.148 +    crc.update(name.getBytes());
  22.149 +    
  22.150 +    long id = crc.getValue();
  22.151 +    
  22.152 +    Statement stmt = conn.createStatement();
  22.153 +    return 1 == stmt.executeUpdate("INSERT INTO Groups (ID, Name) VALUES (" + id + ", '" + name + "')");
  22.154 +  }
  22.155 +  
  22.156 +  public void delete(Article article)
  22.157 +  {
  22.158 +    
  22.159 +  }
  22.160 +  
  22.161 +  public void delete(Group group)
  22.162 +  {
  22.163 +    
  22.164 +  }
  22.165 +  
  22.166 +  public Article getArticle(String messageID)
  22.167 +    throws SQLException
  22.168 +  {
  22.169 +    Statement stmt = this.conn.createStatement();
  22.170 +    ResultSet rs =
  22.171 +      stmt.executeQuery("SELECT * FROM articles WHERE message_id = '" + messageID + "'");
  22.172 +    
  22.173 +    return new Article(rs);
  22.174 +  }
  22.175 +  
  22.176 +  public Article getArticle(long gid, long article_id)
  22.177 +    throws SQLException
  22.178 +  {
  22.179 +    Statement stmt = this.conn.createStatement();
  22.180 +    String sql = "SELECT * FROM articles WHERE article_id = " +
  22.181 +            "(SELECT article_id FROM postings WHERE " +
  22.182 +            "group_id = " + gid + " AND article_id = " + article_id +")";
  22.183 +    ResultSet rs =
  22.184 +      stmt.executeQuery(sql);
  22.185 +    
  22.186 +    if(rs.next())
  22.187 +      return new Article(rs);
  22.188 +    else
  22.189 +      return null;
  22.190 +  }
  22.191 +  
  22.192 +  public ResultSet getArticles()
  22.193 +    throws SQLException
  22.194 +  {
  22.195 +    Statement stmt = conn.createStatement();
  22.196 +    return stmt.executeQuery("SELECT * FROM articles");
  22.197 +  }
  22.198 +  
  22.199 +  /**
  22.200 +   * Reads all Groups from the Database.
  22.201 +   * @return
  22.202 +   * @throws java.sql.SQLException
  22.203 +   */
  22.204 +  public ResultSet getGroups()
  22.205 +    throws SQLException
  22.206 +  {
  22.207 +    Statement stmt = conn.createStatement();
  22.208 +    ResultSet rs = stmt.executeQuery("SELECT * FROM groups");
  22.209 +    
  22.210 +    return rs;
  22.211 +  }
  22.212 +  
  22.213 +  /**
  22.214 +   * Returns the Group that is identified by the name.
  22.215 +   * @param name
  22.216 +   * @return
  22.217 +   * @throws java.sql.SQLException
  22.218 +   */
  22.219 +  public Group getGroup(String name)
  22.220 +    throws SQLException
  22.221 +  {   
  22.222 +    Statement stmt = this.conn.createStatement();
  22.223 +    String sql = "SELECT group_id FROM groups WHERE Name = '%name'";
  22.224 +    StringTemplate tmpl = new StringTemplate(sql);
  22.225 +    tmpl.set("name", name);
  22.226 +    
  22.227 +    ResultSet rs = stmt.executeQuery(tmpl.toString());
  22.228 +  
  22.229 +    if(!rs.next())
  22.230 +      return null;
  22.231 +    else
  22.232 +    {
  22.233 +      long id = rs.getLong("group_id");
  22.234 +      return new Group(name, id);
  22.235 +    }
  22.236 +  }
  22.237 +  
  22.238 +  public int getMaxArticleIndex()
  22.239 +    throws SQLException
  22.240 +  {
  22.241 +    Statement stmt = conn.createStatement();
  22.242 +    ResultSet rs = stmt.executeQuery(
  22.243 +      "SELECT Max(article_index) FROM postings");
  22.244 +    
  22.245 +    if(!rs.next())
  22.246 +      return 0;
  22.247 +    else
  22.248 +      return rs.getInt(1);
  22.249 +  }
  22.250 +  
  22.251 +  public int getLastArticleNumber(Group group)
  22.252 +    throws SQLException
  22.253 +  {
  22.254 +    Statement stmt = conn.createStatement();
  22.255 +    ResultSet rs = stmt.executeQuery(
  22.256 +      "SELECT Max(article_index) FROM postings WHERE group_id = " + group.getID());
  22.257 +    
  22.258 +    if(!rs.next())
  22.259 +      return 0;
  22.260 +    else
  22.261 +      return rs.getInt(1);
  22.262 +  }
  22.263 +  
  22.264 +  public int getFirstArticleNumber(Group group)
  22.265 +    throws SQLException
  22.266 +  {
  22.267 +    Statement stmt = conn.createStatement();
  22.268 +    ResultSet rs = stmt.executeQuery(
  22.269 +      "SELECT Min(article_index) FROM postings WHERE group_id = " + group.getID());
  22.270 +  
  22.271 +    if(!rs.next())
  22.272 +      return 0;
  22.273 +    else
  22.274 +      return rs.getInt(1);
  22.275 +  }
  22.276 +  
  22.277 +  /**
  22.278 +   * Returns a group name identified by the given id.
  22.279 +   * @param id
  22.280 +   * @return
  22.281 +   * @throws java.sql.SQLException
  22.282 +   */
  22.283 +  public String getGroup(int id)
  22.284 +    throws SQLException
  22.285 +  {
  22.286 +    Statement stmt = conn.createStatement();
  22.287 +    ResultSet rs   = stmt.executeQuery(
  22.288 +            "SELECT name FROM groups WHERE group_id = '" + id + "'");
  22.289 +    
  22.290 +    if(rs.next())
  22.291 +    {
  22.292 +      return rs.getString(1);
  22.293 +    }
  22.294 +    else
  22.295 +      return null;
  22.296 +  }
  22.297 +  
  22.298 +  public Article getOldestArticle()
  22.299 +    throws SQLException
  22.300 +  {
  22.301 +    Statement stmt = conn.createStatement();
  22.302 +    ResultSet rs = 
  22.303 +      stmt.executeQuery("SELECT * FROM Articles WHERE Date = (SELECT Min(Date) FROM Articles)");
  22.304 +    
  22.305 +    if(rs.next())
  22.306 +      return new Article(rs);
  22.307 +    else
  22.308 +      return null;
  22.309 +  }
  22.310 +  
  22.311 +  /**
  22.312 +   * Checks if there is a group with the given name in the Database.
  22.313 +   * @param name
  22.314 +   * @return
  22.315 +   * @throws java.sql.SQLException
  22.316 +   */
  22.317 +  public boolean isGroupExisting(String name)
  22.318 +    throws SQLException
  22.319 +  {
  22.320 +    Statement stmt = this.conn.createStatement();
  22.321 +    ResultSet rs   = stmt.executeQuery("SELECT * FROM Groups WHERE Name = '" + name + "'");
  22.322 +    
  22.323 +    return rs.next();
  22.324 +  }
  22.325 +  
  22.326 +  public void updateArticle(Article article)
  22.327 +  {
  22.328 +    
  22.329 +  }
  22.330 +}
    23.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    23.2 +++ b/trunk/com/so/news/storage/Group.java	Tue Jan 20 10:21:03 2009 +0100
    23.3 @@ -0,0 +1,142 @@
    23.4 +/*
    23.5 + *   StarOffice News Server
    23.6 + *   see AUTHORS for the list of contributors
    23.7 + *
    23.8 + *   This program is free software: you can redistribute it and/or modify
    23.9 + *   it under the terms of the GNU General Public License as published by
   23.10 + *   the Free Software Foundation, either version 3 of the License, or
   23.11 + *   (at your option) any later version.
   23.12 + *
   23.13 + *   This program is distributed in the hope that it will be useful,
   23.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   23.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   23.16 + *   GNU General Public License for more details.
   23.17 + *
   23.18 + *   You should have received a copy of the GNU General Public License
   23.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   23.20 + */
   23.21 +
   23.22 +package com.so.news.storage;
   23.23 +
   23.24 +import java.sql.ResultSet;
   23.25 +import java.sql.SQLException;
   23.26 +import java.util.ArrayList;
   23.27 +import java.util.List;
   23.28 +import com.so.news.Debug;
   23.29 +
   23.30 +/**
   23.31 + * Represents a logical Group within this newsserver.
   23.32 + * @author Christian Lins
   23.33 + */
   23.34 +public class Group
   23.35 +{
   23.36 +  private long   id;
   23.37 +  private String name;
   23.38 +
   23.39 +  /**
   23.40 +   * Private constructor.
   23.41 +   * @param name
   23.42 +   * @param id
   23.43 +   */
   23.44 +  Group(String name, long id)
   23.45 +  {
   23.46 +    this.id   = id;
   23.47 +    this.name = name;
   23.48 +  }
   23.49 +  
   23.50 +  /**
   23.51 +   * Returns a Group identified by its full name.
   23.52 +   * @param name
   23.53 +   * @return
   23.54 +   */
   23.55 +  public static Group getByName(String name)
   23.56 +  {
   23.57 +    try
   23.58 +    {
   23.59 +      return Database.getInstance().getGroup(name);
   23.60 +    }
   23.61 +    catch(SQLException ex)
   23.62 +    {
   23.63 +      System.err.println(ex.getLocalizedMessage());
   23.64 +      ex.printStackTrace(Debug.getInstance().getStream());
   23.65 +      return null;
   23.66 +    }
   23.67 +  }
   23.68 +
   23.69 +  /**
   23.70 +   * Returns a list of all groups this server handles.
   23.71 +   * @return
   23.72 +   */
   23.73 +  public static ArrayList<Group> getAll()
   23.74 +  {
   23.75 +    ArrayList<Group> buffer = new ArrayList<Group>();
   23.76 +    
   23.77 +    try
   23.78 +    {
   23.79 +      ResultSet rs = Database.getInstance().getGroups();
   23.80 +      
   23.81 +      while(rs.next())
   23.82 +      {
   23.83 +        String name = rs.getString("name");
   23.84 +        long   id   = rs.getLong("group_id");
   23.85 +        
   23.86 +        Group group = new Group(name, id);
   23.87 +        buffer.add(group);
   23.88 +      }
   23.89 +    }
   23.90 +    catch(SQLException ex)
   23.91 +    {
   23.92 +      ex.printStackTrace(Debug.getInstance().getStream());
   23.93 +      System.err.println(ex.getLocalizedMessage());
   23.94 +    }
   23.95 +    
   23.96 +    return buffer;
   23.97 +  }
   23.98 +
   23.99 +  public List<Article> getAllArticles()
  23.100 +    throws SQLException
  23.101 +  {
  23.102 +    return getAllArticles(getFirstArticle(), getLastArticle());
  23.103 +  }
  23.104 +
  23.105 +  public List<Article> getAllArticles(int first, int last)
  23.106 +  {
  23.107 +    return null;
  23.108 +  }
  23.109 +
  23.110 +  public int getFirstArticle()
  23.111 +    throws SQLException
  23.112 +  {
  23.113 +    return Database.getInstance().getFirstArticleNumber(this);
  23.114 +  }
  23.115 +
  23.116 +  public long getID()
  23.117 +  {
  23.118 +    return id;
  23.119 +  }
  23.120 +
  23.121 +  public int getLastArticle()
  23.122 +    throws SQLException
  23.123 +  {
  23.124 +    return Database.getInstance().getLastArticleNumber(this);
  23.125 +  }
  23.126 +
  23.127 +  public String getName()
  23.128 +  {
  23.129 +    return name;
  23.130 +  }
  23.131 +
  23.132 +  public void setName(String name)
  23.133 +  {
  23.134 +    this.name = name;
  23.135 +  }
  23.136 +
  23.137 +  public int getEstimatedArticleCount()
  23.138 +    throws SQLException
  23.139 +  {
  23.140 +    if (getLastArticle() < getFirstArticle())
  23.141 +      return 0;
  23.142 +    return getLastArticle() - getFirstArticle() + 1;
  23.143 +  }
  23.144 +
  23.145 +}
    24.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    24.2 +++ b/trunk/com/so/news/storage/Purger.java	Tue Jan 20 10:21:03 2009 +0100
    24.3 @@ -0,0 +1,96 @@
    24.4 +/*
    24.5 + *   StarOffice News Server
    24.6 + *   see AUTHORS for the list of contributors
    24.7 + *
    24.8 + *   This program is free software: you can redistribute it and/or modify
    24.9 + *   it under the terms of the GNU General Public License as published by
   24.10 + *   the Free Software Foundation, either version 3 of the License, or
   24.11 + *   (at your option) any later version.
   24.12 + *
   24.13 + *   This program is distributed in the hope that it will be useful,
   24.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   24.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   24.16 + *   GNU General Public License for more details.
   24.17 + *
   24.18 + *   You should have received a copy of the GNU General Public License
   24.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   24.20 + */
   24.21 +
   24.22 +package com.so.news.storage;
   24.23 +
   24.24 +import java.util.Date;
   24.25 +
   24.26 +import com.so.news.Config;
   24.27 +import com.so.news.Debug;
   24.28 +
   24.29 +/**
   24.30 + * The purger is started in configurable intervals to search
   24.31 + * for old messages that can be purged.
   24.32 + * @author Christian Lins
   24.33 + */
   24.34 +public class Purger extends Thread
   24.35 +{
   24.36 +  private int interval;
   24.37 +  
   24.38 +  public Purger()
   24.39 +  {
   24.40 +    setDaemon(true); // Daemons run only along with the main thread
   24.41 +    setPriority(Thread.MIN_PRIORITY);
   24.42 +
   24.43 +    this.interval = Config.getInstance().get("n3tpd.article.lifetime", 30) * 24 * 60 * 60 * 1000; // Milliseconds
   24.44 +    if(this.interval < 0)
   24.45 +      this.interval = Integer.MAX_VALUE;
   24.46 +  }
   24.47 +  
   24.48 +  /**
   24.49 +   * Runloop of this Purger class.
   24.50 +   */
   24.51 +  @Override
   24.52 +  public void run()
   24.53 +  {
   24.54 +    for(;;)
   24.55 +    {
   24.56 +      purge();
   24.57 +
   24.58 +      try
   24.59 +      {
   24.60 +        sleep(interval);
   24.61 +      }
   24.62 +      catch(InterruptedException e)
   24.63 +      {
   24.64 +        e.printStackTrace(Debug.getInstance().getStream());
   24.65 +      }
   24.66 +    }
   24.67 +  }
   24.68 +
   24.69 +  /**
   24.70 +   * Loops through all messages and deletes them if their time
   24.71 +   * has come.
   24.72 +   */
   24.73 +  private void purge()
   24.74 +  {
   24.75 +    Debug.getInstance().log("Purging old messages...");
   24.76 +
   24.77 +    try
   24.78 +    {
   24.79 +      for(;;)
   24.80 +      {
   24.81 +        Article art = null; //Database.getInstance().getOldestArticle();
   24.82 +        if(art == null) // No articles in the database
   24.83 +          break;
   24.84 +        
   24.85 +        if(art.getDate().getTime() < (new Date().getTime() + this.interval))
   24.86 +        {
   24.87 +          Database.getInstance().delete(art);
   24.88 +          Debug.getInstance().log("Deleted: " + art);
   24.89 +        }
   24.90 +        else
   24.91 +          break;
   24.92 +      }
   24.93 +    }
   24.94 +    catch(Exception ex)
   24.95 +    {
   24.96 +      ex.printStackTrace();
   24.97 +    }
   24.98 +  }
   24.99 +}
    25.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    25.2 +++ b/trunk/com/so/news/util/StringTemplate.java	Tue Jan 20 10:21:03 2009 +0100
    25.3 @@ -0,0 +1,77 @@
    25.4 +/*
    25.5 + *   StarOffice News Server
    25.6 + *   see AUTHORS for the list of contributors
    25.7 + *
    25.8 + *   This program is free software: you can redistribute it and/or modify
    25.9 + *   it under the terms of the GNU General Public License as published by
   25.10 + *   the Free Software Foundation, either version 3 of the License, or
   25.11 + *   (at your option) any later version.
   25.12 + *
   25.13 + *   This program is distributed in the hope that it will be useful,
   25.14 + *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   25.15 + *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   25.16 + *   GNU General Public License for more details.
   25.17 + *
   25.18 + *   You should have received a copy of the GNU General Public License
   25.19 + *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
   25.20 + */
   25.21 +
   25.22 +package com.so.news.util;
   25.23 +
   25.24 +import java.util.HashMap;
   25.25 +
   25.26 +/**
   25.27 + * Class that allows simple String template handling.
   25.28 + * @author Christian Lins (christian.lins@web.de)
   25.29 + */
   25.30 +public class StringTemplate 
   25.31 +{
   25.32 +  private String                  str               = null;
   25.33 +  private String                  templateDelimiter = "%";
   25.34 +  private HashMap<String, String> templateValues    = new HashMap<String, String>();
   25.35 +  
   25.36 +  public StringTemplate(String str, String templateDelimiter)
   25.37 +  {
   25.38 +    this.str               = str;
   25.39 +    this.templateDelimiter = templateDelimiter;
   25.40 +  }
   25.41 +  
   25.42 +  public StringTemplate(String str)
   25.43 +  {
   25.44 +    this(str, "%");
   25.45 +  }
   25.46 +  
   25.47 +  public void set(String template, String value)
   25.48 +  {
   25.49 +    this.templateValues.put(template, value);
   25.50 +  }
   25.51 +  
   25.52 +  public void set(String template, long value)
   25.53 +  {
   25.54 +    set(template, Long.toString(value));
   25.55 +  }
   25.56 +  
   25.57 +  public void set(String template, double value)
   25.58 +  {
   25.59 +    set(template, Double.toString(value));
   25.60 +  }
   25.61 +  
   25.62 +  public void set(String template, Object obj)
   25.63 +  {
   25.64 +    set(template, obj.toString());
   25.65 +  }
   25.66 +  
   25.67 +  @Override
   25.68 +  public String toString()
   25.69 +  {
   25.70 +    String ret = new String(str);
   25.71 +    
   25.72 +    for(String key : this.templateValues.keySet())
   25.73 +    {
   25.74 +      String value = this.templateValues.get(key);
   25.75 +      ret = ret.replace(templateDelimiter + key, value);
   25.76 +    }
   25.77 +    
   25.78 +    return ret;
   25.79 +  }
   25.80 +}
    26.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    26.2 +++ b/trunk/helpers/tbl_mysql6_tmpl.sql	Tue Jan 20 10:21:03 2009 +0100
    26.3 @@ -0,0 +1,39 @@
    26.4 +CREATE DATABASE staroffice_news;
    26.5 +
    26.6 +CREATE TABLE groups 
    26.7 +(
    26.8 +  group_id      SERIAL,
    26.9 +  name          VARCHAR(80) NOT NULL,
   26.10 +  flags         INTEGER DEFAULT 0 NOT NULL
   26.11 +);
   26.12 +
   26.13 +CREATE UNIQUE INDEX name_id_index ON groups (name);
   26.14 +
   26.15 +CREATE TABLE articles 
   26.16 +(
   26.17 +  article_id    SERIAL,
   26.18 +  message_id    TEXT,
   26.19 +  header        TEXT,
   26.20 +  body          TEXT
   26.21 +);
   26.22 +
   26.23 +CREATE UNIQUE INDEX article_message_index ON articles (message_id(255));
   26.24 +
   26.25 +CREATE TABLE postings 
   26.26 +(
   26.27 +  group_id      INTEGER,
   26.28 +  article_id    INTEGER,
   26.29 +  article_index INTEGER NOT NULL
   26.30 +);
   26.31 +
   26.32 +CREATE UNIQUE INDEX posting_article_index ON postings (article_id);
   26.33 +
   26.34 +CREATE TABLE subscriptions 
   26.35 +(
   26.36 +  group_id    INTEGER
   26.37 +);
   26.38 +    
   26.39 +CREATE TABLE overview 
   26.40 +(
   26.41 +  header      TEXT
   26.42 +);
    27.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    27.2 +++ b/trunk/rfc3977.txt	Tue Jan 20 10:21:03 2009 +0100
    27.3 @@ -0,0 +1,6998 @@
    27.4 +
    27.5 +Network Working Group                                         C. Feather
    27.6 +Request for Comments: 3977                                      THUS plc
    27.7 +Obsoletes: 977                                              October 2006
    27.8 +Updates: 2980
    27.9 +Category: Standards Track
   27.10 +
   27.11 +
   27.12 +                 Network News Transfer Protocol (NNTP)
   27.13 +
   27.14 +Status of This Memo
   27.15 +
   27.16 +   This document specifies an Internet standards track protocol for the
   27.17 +   Internet community, and requests discussion and suggestions for
   27.18 +   improvements.  Please refer to the current edition of the "Internet
   27.19 +   Official Protocol Standards" (STD 1) for the standardization state
   27.20 +   and status of this protocol.  Distribution of this memo is unlimited.
   27.21 +
   27.22 +Copyright Notice
   27.23 +
   27.24 +   Copyright (C) The Internet Society (2006).
   27.25 +
   27.26 +Abstract
   27.27 +
   27.28 +   The Network News Transfer Protocol (NNTP) has been in use in the
   27.29 +   Internet for a decade, and remains one of the most popular protocols
   27.30 +   (by volume) in use today.  This document is a replacement for
   27.31 +   RFC 977, and officially updates the protocol specification.  It
   27.32 +   clarifies some vagueness in RFC 977, includes some new base
   27.33 +   functionality, and provides a specific mechanism to add standardized
   27.34 +   extensions to NNTP.
   27.35 +
   27.36 +Table of Contents
   27.37 +
   27.38 +   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .  3
   27.39 +     1.1.  Author's Note . . . . . . . . . . . . . . . . . . . . . .  4
   27.40 +   2.  Notation  . . . . . . . . . . . . . . . . . . . . . . . . . .  5
   27.41 +   3.  Basic Concepts  . . . . . . . . . . . . . . . . . . . . . . .  6
   27.42 +     3.1.  Commands and Responses  . . . . . . . . . . . . . . . . .  6
   27.43 +       3.1.1.  Multi-line Data Blocks . . . . . . . . . . . . . . . . 8
   27.44 +     3.2.  Response Codes  . . . . . . . . . . . . . . . . . . . . .  9
   27.45 +       3.2.1.  Generic Response Codes  . . . . . . . . . . . . . . . 10
   27.46 +         3.2.1.1.  Examples  . . . . . . . . . . . . . . . . . . . . 12
   27.47 +     3.3.  Capabilities and Extensions . . . . . . . . . . . . . . . 14
   27.48 +       3.3.1.  Capability Descriptions . . . . . . . . . . . . . . . 14
   27.49 +       3.3.2.  Standard Capabilities . . . . . . . . . . . . . . . . 15
   27.50 +       3.3.3.  Extensions  . . . . . . . . . . . . . . . . . . . . . 16
   27.51 +       3.3.4.  Initial IANA Register . . . . . . . . . . . . . . . . 18
   27.52 +     3.4.  Mandatory and Optional Commands . . . . . . . . . . . . . 20
   27.53 +
   27.54 +
   27.55 +
   27.56 +Feather                     Standards Track                     [Page 1]
   27.57 +
   27.58 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
   27.59 +
   27.60 +
   27.61 +       3.4.1.  Reading and Transit Servers . . . . . . . . . . . . . 21
   27.62 +       3.4.2.  Mode Switching  . . . . . . . . . . . . . . . . . . . 21
   27.63 +     3.5.  Pipelining  . . . . . . . . . . . . . . . . . . . . . . . 22
   27.64 +       3.5.1.  Examples  . . . . . . . . . . . . . . . . . . . . . . 23
   27.65 +     3.6.  Articles  . . . . . . . . . . . . . . . . . . . . . . . . 24
   27.66 +   4.  The WILDMAT Format  . . . . . . . . . . . . . . . . . . . . . 25
   27.67 +     4.1.  Wildmat Syntax  . . . . . . . . . . . . . . . . . . . . . 26
   27.68 +     4.2.  Wildmat Semantics . . . . . . . . . . . . . . . . . . . . 26
   27.69 +     4.3.  Extensions  . . . . . . . . . . . . . . . . . . . . . . . 27
   27.70 +     4.4.  Examples  . . . . . . . . . . . . . . . . . . . . . . . . 27
   27.71 +   5.  Session Administration Commands . . . . . . . . . . . . . . . 28
   27.72 +     5.1.  Initial Connection  . . . . . . . . . . . . . . . . . . . 28
   27.73 +     5.2.  CAPABILITIES  . . . . . . . . . . . . . . . . . . . . . . 29
   27.74 +     5.3.  MODE READER . . . . . . . . . . . . . . . . . . . . . . . 32
   27.75 +     5.4.  QUIT  . . . . . . . . . . . . . . . . . . . . . . . . . . 34
   27.76 +   6.  Article Posting and Retrieval . . . . . . . . . . . . . . . . 35
   27.77 +     6.1.  Group and Article Selection . . . . . . . . . . . . . . . 36
   27.78 +       6.1.1.  GROUP . . . . . . . . . . . . . . . . . . . . . . . . 36
   27.79 +       6.1.2.  LISTGROUP . . . . . . . . . . . . . . . . . . . . . . 39
   27.80 +       6.1.3.  LAST  . . . . . . . . . . . . . . . . . . . . . . . . 42
   27.81 +       6.1.4.  NEXT  . . . . . . . . . . . . . . . . . . . . . . . . 44
   27.82 +     6.2.  Retrieval of Articles and Article Sections  . . . . . . . 45
   27.83 +       6.2.1.  ARTICLE . . . . . . . . . . . . . . . . . . . . . . . 46
   27.84 +       6.2.2.  HEAD  . . . . . . . . . . . . . . . . . . . . . . . . 49
   27.85 +       6.2.3.  BODY  . . . . . . . . . . . . . . . . . . . . . . . . 51
   27.86 +       6.2.4.  STAT  . . . . . . . . . . . . . . . . . . . . . . . . 53
   27.87 +     6.3.  Article Posting . . . . . . . . . . . . . . . . . . . . . 56
   27.88 +       6.3.1.  POST  . . . . . . . . . . . . . . . . . . . . . . . . 56
   27.89 +       6.3.2.  IHAVE . . . . . . . . . . . . . . . . . . . . . . . . 58
   27.90 +   7.  Information Commands  . . . . . . . . . . . . . . . . . . . . 61
   27.91 +     7.1.  DATE  . . . . . . . . . . . . . . . . . . . . . . . . . . 61
   27.92 +     7.2.  HELP  . . . . . . . . . . . . . . . . . . . . . . . . . . 62
   27.93 +     7.3.  NEWGROUPS . . . . . . . . . . . . . . . . . . . . . . . . 63
   27.94 +     7.4.  NEWNEWS . . . . . . . . . . . . . . . . . . . . . . . . . 64
   27.95 +     7.5.  Time  . . . . . . . . . . . . . . . . . . . . . . . . . . 65
   27.96 +       7.5.1.  Examples  . . . . . . . . . . . . . . . . . . . . . . 66
   27.97 +     7.6.  The LIST Commands . . . . . . . . . . . . . . . . . . . . 66
   27.98 +       7.6.1.  LIST  . . . . . . . . . . . . . . . . . . . . . . . . 67
   27.99 +       7.6.2.  Standard LIST Keywords  . . . . . . . . . . . . . . . 69
  27.100 +       7.6.3.  LIST ACTIVE . . . . . . . . . . . . . . . . . . . . . 70
  27.101 +       7.6.4.  LIST ACTIVE.TIMES . . . . . . . . . . . . . . . . . . 71
  27.102 +       7.6.5.  LIST DISTRIB.PATS . . . . . . . . . . . . . . . . . . 72
  27.103 +       7.6.6.  LIST NEWSGROUPS . . . . . . . . . . . . . . . . . . . 73
  27.104 +   8.  Article Field Access Commands . . . . . . . . . . . . . . . . 73
  27.105 +     8.1.  Article Metadata  . . . . . . . . . . . . . . . . . . . . 74
  27.106 +       8.1.1.  The :bytes Metadata Item  . . . . . . . . . . . . . . 74
  27.107 +       8.1.2.  The :lines Metadata Item  . . . . . . . . . . . . . . 75
  27.108 +     8.2.  Database Consistency  . . . . . . . . . . . . . . . . . . 75
  27.109 +
  27.110 +
  27.111 +
  27.112 +Feather                     Standards Track                     [Page 2]
  27.113 +
  27.114 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.115 +
  27.116 +
  27.117 +     8.3.  OVER  . . . . . . . . . . . . . . . . . . . . . . . . . . 76
  27.118 +     8.4.  LIST OVERVIEW.FMT . . . . . . . . . . . . . . . . . . . . 81
  27.119 +     8.5.  HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
  27.120 +     8.6.  LIST HEADERS  . . . . . . . . . . . . . . . . . . . . . . 87
  27.121 +   9.  Augmented BNF Syntax for NNTP . . . . . . . . . . . . . . . . 90
  27.122 +     9.1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . 90
  27.123 +     9.2.  Commands  . . . . . . . . . . . . . . . . . . . . . . . . 92
  27.124 +     9.3.  Command Continuation  . . . . . . . . . . . . . . . . . . 93
  27.125 +     9.4.  Responses . . . . . . . . . . . . . . . . . . . . . . . . 93
  27.126 +       9.4.1.  Generic Responses . . . . . . . . . . . . . . . . . . 93
  27.127 +       9.4.2.  Initial Response Line Contents  . . . . . . . . . . . 94
  27.128 +       9.4.3.  Multi-line Response Contents  . . . . . . . . . . . . 94
  27.129 +     9.5.  Capability Lines  . . . . . . . . . . . . . . . . . . . . 95
  27.130 +     9.6.  LIST Variants . . . . . . . . . . . . . . . . . . . . . . 96
  27.131 +     9.7.  Articles  . . . . . . . . . . . . . . . . . . . . . . . . 97
  27.132 +     9.8.  General Non-terminals . . . . . . . . . . . . . . . . . . 97
  27.133 +     9.9.  Extensions and Validation . . . . . . . . . . . . . . . . 99
  27.134 +   10. Internationalisation Considerations . . . . . . . . . . . . .100
  27.135 +     10.1. Introduction and Historical Situation . . . . . . . . . .100
  27.136 +     10.2. This Specification  . . . . . . . . . . . . . . . . . . .101
  27.137 +     10.3. Outstanding Issues  . . . . . . . . . . . . . . . . . . .102
  27.138 +   11. IANA Considerations . . . . . . . . . . . . . . . . . . . . .103
  27.139 +   12. Security Considerations . . . . . . . . . . . . . . . . . . .103
  27.140 +     12.1. Personal and Proprietary Information  . . . . . . . . . .104
  27.141 +     12.2. Abuse of Server Log Information . . . . . . . . . . . . .104
  27.142 +     12.3. Weak Authentication and Access Control  . . . . . . . . .104
  27.143 +     12.4. DNS Spoofing  . . . . . . . . . . . . . . . . . . . . . .104
  27.144 +     12.5. UTF-8 Issues  . . . . . . . . . . . . . . . . . . . . . .105
  27.145 +     12.6. Caching of Capability Lists . . . . . . . . . . . . . . .106
  27.146 +   13. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .107
  27.147 +   14. References  . . . . . . . . . . . . . . . . . . . . . . . . .110
  27.148 +     14.1. Normative References  . . . . . . . . . . . . . . . . . .110
  27.149 +     14.2. Informative References  . . . . . . . . . . . . . . . . .110
  27.150 +   A.  Interaction with Other Specifications . . . . . . . . . . . .112
  27.151 +     A.1.  Header Folding  . . . . . . . . . . . . . . . . . . . . .112
  27.152 +     A.2.  Message-IDs . . . . . . . . . . . . . . . . . . . . . . .112
  27.153 +     A.3.  Article Posting . . . . . . . . . . . . . . . . . . . . .114
  27.154 +   B.  Summary of Commands . . . . . . . . . . . . . . . . . . . . .115
  27.155 +   C.  Summary of Response Codes . . . . . . . . . . . . . . . . . .117
  27.156 +   D.  Changes from RFC 977  . . . . . . . . . . . . . . . . . . . .121
  27.157 +
  27.158 +1.  Introduction
  27.159 +
  27.160 +   This document specifies the Network News Transfer Protocol (NNTP),
  27.161 +   which is used for the distribution, inquiry, retrieval, and posting
  27.162 +   of Netnews articles using a reliable stream-based mechanism.  For
  27.163 +   news-reading clients, NNTP enables retrieval of news articles that
  27.164 +
  27.165 +
  27.166 +
  27.167 +
  27.168 +Feather                     Standards Track                     [Page 3]
  27.169 +
  27.170 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.171 +
  27.172 +
  27.173 +   are stored in a central database, giving subscribers the ability to
  27.174 +   select only those articles they wish to read.
  27.175 +
  27.176 +   The Netnews model provides for indexing, cross-referencing, and
  27.177 +   expiration of aged messages.  NNTP is designed for efficient
  27.178 +   transmission of Netnews articles over a reliable full duplex
  27.179 +   communication channel.
  27.180 +
  27.181 +   Although the protocol specification in this document is largely
  27.182 +   compatible with the version specified in RFC 977 [RFC977], a number
  27.183 +   of changes are summarised in Appendix D.  In particular:
  27.184 +
  27.185 +   o  the default character set is changed from US-ASCII [ANSI1986] to
  27.186 +      UTF-8 [RFC3629] (note that US-ASCII is a subset of UTF-8);
  27.187 +
  27.188 +   o  a number of commands that were optional in RFC 977 or that have
  27.189 +      been taken from RFC 2980 [RFC2980] are now mandatory; and
  27.190 +
  27.191 +   o  a CAPABILITIES command has been added to allow clients to
  27.192 +      determine what functionality is available from a server.
  27.193 +
  27.194 +   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
  27.195 +   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
  27.196 +   document are to be interpreted as described in RFC 2119 [RFC2119].
  27.197 +
  27.198 +   An implementation is not compliant if it fails to satisfy one or more
  27.199 +   of the MUST requirements for this protocol.  An implementation that
  27.200 +   satisfies all the MUST and all the SHOULD requirements for its
  27.201 +   protocols is said to be "unconditionally compliant"; one that
  27.202 +   satisfies all the MUST requirements but not all the SHOULD
  27.203 +   requirements for NNTP is said to be "conditionally compliant".
  27.204 +
  27.205 +   For the remainder of this document, the terms "client" and "client
  27.206 +   host" refer to a host making use of the NNTP service, while the terms
  27.207 +   "server" and "server host" refer to a host that offers the NNTP
  27.208 +   service.
  27.209 +
  27.210 +1.1.  Author's Note
  27.211 +
  27.212 +   This document is written in XML using an NNTP-specific DTD.  Custom
  27.213 +   software is used to convert this to RFC 2629 [RFC2629] format, and
  27.214 +   then the public "xml2rfc" package to further reduce this to text,
  27.215 +   nroff source, and HTML.
  27.216 +
  27.217 +   No perl was used in producing this document.
  27.218 +
  27.219 +
  27.220 +
  27.221 +
  27.222 +
  27.223 +
  27.224 +Feather                     Standards Track                     [Page 4]
  27.225 +
  27.226 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.227 +
  27.228 +
  27.229 +2.  Notation
  27.230 +
  27.231 +   The following notational conventions are used in this document.
  27.232 +
  27.233 +     UPPERCASE     indicates literal text to be included in the
  27.234 +                   command.
  27.235 +
  27.236 +     lowercase     indicates a token described elsewhere.
  27.237 +
  27.238 +     [brackets]    indicate that the enclosed material is optional.
  27.239 +
  27.240 +     elliptical    indicates that the argument may be repeated any
  27.241 +     ... marks     number of times (it must occur at least once).
  27.242 +
  27.243 +     vertical|bar  indicates a choice of two mutually exclusive
  27.244 +                   arguments (exactly one must be provided).
  27.245 +
  27.246 +   The name "message-id" for a command or response argument indicates
  27.247 +   that it is the message-id of an article as described in Section 3.6,
  27.248 +   including the angle brackets.
  27.249 +
  27.250 +   The name "wildmat" for an argument indicates that it is a wildmat as
  27.251 +   defined in Section 4.  If the argument does not meet the requirements
  27.252 +   of that section (for example, if it does not fit the grammar of
  27.253 +   Section 4.1), the NNTP server MAY place some interpretation on it
  27.254 +   (not specified by this document) or otherwise MUST treat it as a
  27.255 +   syntax error.
  27.256 +
  27.257 +   Responses for each command will be described in tables listing the
  27.258 +   required format of a response followed by the meaning that should be
  27.259 +   ascribed to that response.
  27.260 +
  27.261 +   The terms "NUL", "TAB", "LF", "CR, and "space" refer to the octets
  27.262 +   %x00, %x09, %x0A, %x0D, and %x20, respectively (that is, the octets
  27.263 +   with those codes in US-ASCII [ANSI1986] and thus in UTF-8 [RFC3629]).
  27.264 +   The term "CRLF" or "CRLF pair" means the sequence CR immediately
  27.265 +   followed by LF (that is, %x0D.0A).  A "printable US-ASCII character"
  27.266 +   is an octet in the range %x21-7E.  Quoted characters refer to the
  27.267 +   octets with those codes in US-ASCII (so "." and "<" refer to %x2E and
  27.268 +   %x3C) and will always be printable US-ASCII characters; similarly,
  27.269 +   "digit" refers to the octets %x30-39.
  27.270 +
  27.271 +   A "keyword" MUST consist only of US-ASCII letters, digits, and the
  27.272 +   characters dot (".") and dash ("-") and MUST begin with a letter.
  27.273 +   Keywords MUST be at least three characters in length.
  27.274 +
  27.275 +
  27.276 +
  27.277 +
  27.278 +
  27.279 +
  27.280 +Feather                     Standards Track                     [Page 5]
  27.281 +
  27.282 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.283 +
  27.284 +
  27.285 +   Examples in this document are not normative but serve to illustrate
  27.286 +   usages, arguments, and responses.  In the examples, a "[C]" will be
  27.287 +   used to represent the client host and an "[S]" will be used to
  27.288 +   represent the server host.  Most of the examples do not rely on a
  27.289 +   particular server state.  In some cases, however, they do assume that
  27.290 +   the currently selected newsgroup (see the GROUP command,
  27.291 +   Section 6.1.1) is invalid; when so, this is indicated at the start of
  27.292 +   the example.  Examples may use commands or other keywords not defined
  27.293 +   in this specification (such as an XENCRYPT command).  These will be
  27.294 +   used to illustrate some point and do not imply that any such command
  27.295 +   is defined elsewhere or needs to exist in any particular
  27.296 +   implementation.
  27.297 +
  27.298 +   Terms that might be read as specifying details of a client or server
  27.299 +   implementation, such as "database", are used simply to ease
  27.300 +   description.  Provided that implementations conform to the protocol
  27.301 +   and format specifications in this document, no specific technique is
  27.302 +   mandated.
  27.303 +
  27.304 +3.  Basic Concepts
  27.305 +
  27.306 +3.1.  Commands and Responses
  27.307 +
  27.308 +   NNTP operates over any reliable bi-directional 8-bit-wide data stream
  27.309 +   channel.  When the connection is established, the NNTP server host
  27.310 +   MUST send a greeting.  The client host and server host then exchange
  27.311 +   commands and responses (respectively) until the connection is closed
  27.312 +   or aborted.  If the connection used is TCP, then the server host
  27.313 +   starts the NNTP service by listening on a TCP port.  When a client
  27.314 +   host wishes to make use of the service, it MUST establish a TCP
  27.315 +   connection with the server host by connecting to that host on the
  27.316 +   same port on which the server is listening.
  27.317 +
  27.318 +   The character set for all NNTP commands is UTF-8 [RFC3629].  Commands
  27.319 +   in NNTP MUST consist of a keyword, which MAY be followed by one or
  27.320 +   more arguments.  A CRLF pair MUST terminate all commands.  Multiple
  27.321 +   commands MUST NOT be on the same line.  Unless otherwise noted
  27.322 +   elsewhere in this document, arguments SHOULD consist of printable US-
  27.323 +   ASCII characters.  Keywords and arguments MUST each be separated by
  27.324 +   one or more space or TAB characters.  Command lines MUST NOT exceed
  27.325 +   512 octets, which includes the terminating CRLF pair.  The arguments
  27.326 +   MUST NOT exceed 497 octets.  A server MAY relax these limits for
  27.327 +   commands defined in an extension.
  27.328 +
  27.329 +   Where this specification permits UTF-8 characters outside the range
  27.330 +   of U+0000 to U+007F, implementations MUST NOT use the Byte Order Mark
  27.331 +   (U+FEFF, encoding %xEF.BB.BF) and MUST use the Word Joiner (U+2060,
  27.332 +   encoding %xE2.91.A0) for the meaning Zero Width No-Break Space in
  27.333 +
  27.334 +
  27.335 +
  27.336 +Feather                     Standards Track                     [Page 6]
  27.337 +
  27.338 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.339 +
  27.340 +
  27.341 +   command lines and the initial lines of responses.  Implementations
  27.342 +   SHOULD apply these same principles throughout.
  27.343 +
  27.344 +   The term "character" means a single Unicode code point.
  27.345 +   Implementations are not required to carry out Unicode normalisation.
  27.346 +   Thus, U+0084 (A-dieresis) is one character, while U+0041 U+0308 (A
  27.347 +   composed with dieresis) is two; the two need not be treated as
  27.348 +   equivalent.
  27.349 +
  27.350 +   Commands may have variants; if so, they use a second keyword
  27.351 +   immediately after the first to indicate which variant is required.
  27.352 +   The only such commands in this specification are LIST and MODE.  Note
  27.353 +   that such variants are sometimes referred to as if they were commands
  27.354 +   in their own right: "the LIST ACTIVE" command should be read as
  27.355 +   shorthand for "the ACTIVE variant of the LIST command".
  27.356 +
  27.357 +   Keywords are case insensitive; the case of keywords for commands MUST
  27.358 +   be ignored by the server.  Command and response arguments are case or
  27.359 +   language specific only when stated, either in this document or in
  27.360 +   other relevant specifications.
  27.361 +
  27.362 +   In some cases, a command involves more data than just a single line.
  27.363 +   The further data may be sent either immediately after the command
  27.364 +   line (there are no instances of this in this specification, but there
  27.365 +   are in extensions such as [NNTP-STREAM]) or following a request from
  27.366 +   the server (indicated by a 3xx response).
  27.367 +
  27.368 +   Each response MUST start with a three-digit response code that is
  27.369 +   sufficient to distinguish all responses.  Certain valid responses are
  27.370 +   defined to be multi-line; for all others, the response is contained
  27.371 +   in a single line.  The initial line of the response MUST NOT exceed
  27.372 +   512 octets, which includes the response code and the terminating CRLF
  27.373 +   pair; an extension MAY specify a greater maximum for commands that it
  27.374 +   defines, but not for any other command.  Single-line responses
  27.375 +   consist of an initial line only.  Multi-line responses consist of an
  27.376 +   initial line followed by a multi-line data block.
  27.377 +
  27.378 +   An NNTP server MAY have an inactivity autologout timer.  Such a timer
  27.379 +   SHOULD be of at least three minutes' duration, with the exception
  27.380 +   that there MAY be a shorter limit on how long the server is willing
  27.381 +   to wait for the first command from the client.  The receipt of any
  27.382 +   command from the client during the timer interval SHOULD suffice to
  27.383 +   reset the autologout timer.  Similarly, the receipt of any
  27.384 +   significant amount of data from a client that is sending a multi-line
  27.385 +   data block (such as during a POST or IHAVE command) SHOULD suffice to
  27.386 +   reset the autologout timer.  When the timer expires, the server
  27.387 +   SHOULD close the connection without sending any response to the
  27.388 +   client.
  27.389 +
  27.390 +
  27.391 +
  27.392 +Feather                     Standards Track                     [Page 7]
  27.393 +
  27.394 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.395 +
  27.396 +
  27.397 +3.1.1.  Multi-line Data Blocks
  27.398 +
  27.399 +   A multi-line data block is used in certain commands and responses.
  27.400 +   It MUST adhere to the following rules:
  27.401 +
  27.402 +   1.  The block consists of a sequence of zero or more "lines", each
  27.403 +       being a stream of octets ending with a CRLF pair.  Apart from
  27.404 +       those line endings, the stream MUST NOT include the octets NUL,
  27.405 +       LF, or CR.
  27.406 +
  27.407 +   2.  In a multi-line response, the block immediately follows the CRLF
  27.408 +       at the end of the initial line of the response.  When used in any
  27.409 +       other context, the specific command will define when the block is
  27.410 +       sent.
  27.411 +
  27.412 +   3.  If any line of the data block begins with the "termination octet"
  27.413 +       ("." or %x2E), that line MUST be "dot-stuffed" by prepending an
  27.414 +       additional termination octet to that line of the block.
  27.415 +
  27.416 +   4.  The lines of the block MUST be followed by a terminating line
  27.417 +       consisting of a single termination octet followed by a CRLF pair
  27.418 +       in the normal way.  Thus, unless it is empty, a multi-line block
  27.419 +       is always terminated with the five octets CRLF "." CRLF
  27.420 +       (%x0D.0A.2E.0D.0A).
  27.421 +
  27.422 +   5.  When a multi-line block is interpreted, the "dot-stuffing" MUST
  27.423 +       be undone; i.e., the recipient MUST ensure that, in any line
  27.424 +       beginning with the termination octet followed by octets other
  27.425 +       than a CRLF pair, that initial termination octet is disregarded.
  27.426 +
  27.427 +   6.  Likewise, the terminating line ("." CRLF or %x2E.0D.0A) MUST NOT
  27.428 +       be considered part of the multi-line block; i.e., the recipient
  27.429 +       MUST ensure that any line beginning with the termination octet
  27.430 +       followed immediately by a CRLF pair is disregarded.  (The first
  27.431 +       CRLF pair of the terminating CRLF "." CRLF of a non-empty block
  27.432 +       is, of course, part of the last line of the block.)
  27.433 +
  27.434 +   Note that texts using an encoding (such as UTF-16 or UTF-32) that may
  27.435 +   contain the octets NUL, LF, or CR other than a CRLF pair cannot be
  27.436 +   reliably conveyed in the above format (that is, they violate the MUST
  27.437 +   requirement above).  However, except when stated otherwise, this
  27.438 +   specification does not require the content to be UTF-8, and therefore
  27.439 +   (subject to that same requirement) it MAY include octets above and
  27.440 +   below 128 mixed arbitrarily.
  27.441 +
  27.442 +   This document does not place any limit on the length of a line in a
  27.443 +   multi-line block.  However, the standards that define the format of
  27.444 +   articles may do so.
  27.445 +
  27.446 +
  27.447 +
  27.448 +Feather                     Standards Track                     [Page 8]
  27.449 +
  27.450 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.451 +
  27.452 +
  27.453 +3.2.  Response Codes
  27.454 +
  27.455 +   Each response MUST begin with a three-digit status indicator.  These
  27.456 +   are status reports from the server and indicate the response to the
  27.457 +   last command received from the client.
  27.458 +
  27.459 +   The first digit of the response broadly indicates the success,
  27.460 +   failure, or progress of the previous command:
  27.461 +
  27.462 +      1xx - Informative message
  27.463 +      2xx - Command completed OK
  27.464 +      3xx - Command OK so far; send the rest of it
  27.465 +      4xx - Command was syntactically correct but failed for some reason
  27.466 +      5xx - Command unknown, unsupported, unavailable, or syntax error
  27.467 +
  27.468 +   The next digit in the code indicates the function response category:
  27.469 +
  27.470 +      x0x - Connection, setup, and miscellaneous messages
  27.471 +      x1x - Newsgroup selection
  27.472 +      x2x - Article selection
  27.473 +      x3x - Distribution functions
  27.474 +      x4x - Posting
  27.475 +      x8x - Reserved for authentication and privacy extensions
  27.476 +      x9x - Reserved for private use (non-standard extensions)
  27.477 +
  27.478 +   Certain responses contain arguments such as numbers and names in
  27.479 +   addition to the status indicator.  In those cases, to simplify
  27.480 +   interpretation by the client, the number and type of such arguments
  27.481 +   is fixed for each response code, as is whether the code is
  27.482 +   single-line or multi-line.  Any extension MUST follow this principle
  27.483 +   as well.  Note that, for historical reasons, the 211 response code is
  27.484 +   an exception to this in that the response may be single-line or
  27.485 +   multi-line depending on the command (GROUP or LISTGROUP) that
  27.486 +   generated it.  In all other cases, the client MUST only use the
  27.487 +   status indicator itself to determine the nature of the response.  The
  27.488 +   exact response codes that can be returned by any given command are
  27.489 +   detailed in the description of that command.
  27.490 +
  27.491 +   Arguments MUST be separated from the numeric status indicator and
  27.492 +   from each other by a single space.  All numeric arguments MUST be in
  27.493 +   base 10 (decimal) format and MAY have leading zeros.  String
  27.494 +   arguments MUST contain at least one character and MUST NOT contain
  27.495 +   TAB, LF, CR, or space.  The server MAY add any text after the
  27.496 +   response code or last argument, as appropriate, and the client MUST
  27.497 +   NOT make decisions based on this text.  Such text MUST be separated
  27.498 +   from the numeric status indicator or the last argument by at least
  27.499 +   one space.
  27.500 +
  27.501 +
  27.502 +
  27.503 +
  27.504 +Feather                     Standards Track                     [Page 9]
  27.505 +
  27.506 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.507 +
  27.508 +
  27.509 +   The server MUST respond to any command with the appropriate generic
  27.510 +   response (given in Section 3.2.1) if it represents the situation.
  27.511 +   Otherwise, each recognized command MUST return one of the response
  27.512 +   codes specifically listed in its description or in an extension.  A
  27.513 +   server MAY provide extensions to this specification, including new
  27.514 +   commands, new variants or features of existing commands, and other
  27.515 +   ways of changing the internal state of the server.  However, the
  27.516 +   server MUST NOT produce any other responses to a client that does not
  27.517 +   invoke any of the additional features.  (Therefore, a client that
  27.518 +   restricts itself to this specification will only receive the
  27.519 +   responses that are listed.)
  27.520 +
  27.521 +   If a client receives an unexpected response, it SHOULD use the first
  27.522 +   digit of the response to determine the result.  For example, an
  27.523 +   unexpected 2xx should be taken as success, and an unexpected 4xx or
  27.524 +   5xx as failure.
  27.525 +
  27.526 +   Response codes not specified in this document MAY be used for any
  27.527 +   installation-specific additional commands also not specified.  These
  27.528 +   SHOULD be chosen to fit the pattern of x9x specified above.
  27.529 +
  27.530 +   Neither this document nor any registered extension (see
  27.531 +   Section 3.3.3) will specify any response codes of the x9x pattern.
  27.532 +   (Implementers of extensions are accordingly cautioned not to use such
  27.533 +   responses for extensions that may subsequently be submitted for
  27.534 +   registration.)
  27.535 +
  27.536 +3.2.1.  Generic Response Codes
  27.537 +
  27.538 +   The server MUST respond to any command with the appropriate one of
  27.539 +   the following generic responses if it represents the situation.
  27.540 +
  27.541 +   If the command is not recognized, or if it is an optional command
  27.542 +   that is not implemented by the server, the response code 500 MUST be
  27.543 +   returned.
  27.544 +
  27.545 +   If there is a syntax error in the arguments of a recognized command,
  27.546 +   including the case where more arguments are provided than the command
  27.547 +   specifies or the command line is longer than the server accepts, the
  27.548 +   response code 501 MUST be returned.  The line MUST NOT be truncated
  27.549 +   or split and then interpreted.  Note that where a command has
  27.550 +   variants depending on a second keyword (e.g., LIST ACTIVE and LIST
  27.551 +   NEWSGROUPS), 501 MUST be used when the base command is implemented
  27.552 +   but the requested variant is not, and 500 MUST be used only when the
  27.553 +   base command itself is not implemented.
  27.554 +
  27.555 +   If an argument is required to be a base64-encoded string [RFC4648]
  27.556 +   (there are no such arguments in this specification, but there may be
  27.557 +
  27.558 +
  27.559 +
  27.560 +Feather                     Standards Track                    [Page 10]
  27.561 +
  27.562 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.563 +
  27.564 +
  27.565 +   in extensions) and is not validly encoded, the response code 504 MUST
  27.566 +   be returned.
  27.567 +
  27.568 +   If the server experiences an internal fault or problem that means it
  27.569 +   is unable to carry out the command (for example, a necessary file is
  27.570 +   missing or a necessary service could not be contacted), the response
  27.571 +   code 403 MUST be returned.  If the server recognizes the command but
  27.572 +   does not provide an optional feature (for example, because it does
  27.573 +   not store the required information), or if it only handles a subset
  27.574 +   of legitimate cases (see the HDR command, Section 8.5, for an
  27.575 +   example), the response code 503 MUST be returned.
  27.576 +
  27.577 +   If the client is not authorized to use the specified facility when
  27.578 +   the server is in its current state, then the appropriate one of the
  27.579 +   following response codes MUST be used.
  27.580 +
  27.581 +   502: It is necessary to terminate the connection and to start a new
  27.582 +      one with the appropriate authority before the command can be used.
  27.583 +      Historically, some mode-switching servers (see Section 3.4.1) used
  27.584 +      this response to indicate that this command will become available
  27.585 +      after the MODE READER command (Section 5.3) is used, but this
  27.586 +      usage does not conform to this specification and MUST NOT be used.
  27.587 +      Note that the server MUST NOT close the connection immediately
  27.588 +      after a 502 response except at the initial connection
  27.589 +      (Section 5.1) and with the MODE READER command.
  27.590 +
  27.591 +   480: The client must authenticate itself to the server (that is, it
  27.592 +      must provide information as to the identity of the client) before
  27.593 +      the facility can be used on this connection.  This will involve
  27.594 +      the use of an authentication extension such as [NNTP-AUTH].
  27.595 +
  27.596 +   483: The client must negotiate appropriate privacy protection on the
  27.597 +      connection.  This will involve the use of a privacy extension such
  27.598 +      as [NNTP-TLS].
  27.599 +
  27.600 +   401: The client must change the state of the connection in some other
  27.601 +      manner.  The first argument of the response MUST be the capability
  27.602 +      label (see Section 5.2) of the facility that provides the
  27.603 +      necessary mechanism (usually an extension, which may be a private
  27.604 +      extension).  The server MUST NOT use this response code except as
  27.605 +      specified by the definition of the capability in question.
  27.606 +
  27.607 +   If the server has to terminate the connection for some reason, it
  27.608 +   MUST give a 400 response code to the next command and then
  27.609 +   immediately close the connection.  Following a 400 response, clients
  27.610 +   SHOULD NOT simply reconnect immediately and retry the same actions.
  27.611 +   Rather, a client SHOULD either use an exponentially increasing delay
  27.612 +   between retries (e.g., double the waiting time after each 400
  27.613 +
  27.614 +
  27.615 +
  27.616 +Feather                     Standards Track                    [Page 11]
  27.617 +
  27.618 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.619 +
  27.620 +
  27.621 +   response) or present any associated text to the user for them to
  27.622 +   decide whether and when to retry.
  27.623 +
  27.624 +   The client MUST be prepared to receive any of these responses for any
  27.625 +   command (except, of course, that the server MUST NOT generate a 500
  27.626 +   response code for mandatory commands).
  27.627 +
  27.628 +3.2.1.1.  Examples
  27.629 +
  27.630 +   Example of an unknown command:
  27.631 +
  27.632 +      [C] MAIL
  27.633 +      [S] 500 Unknown command
  27.634 +
  27.635 +   Example of an unsupported command:
  27.636 +
  27.637 +      [C] CAPABILITIES
  27.638 +      [S] 101 Capability list:
  27.639 +      [S] VERSION 2
  27.640 +      [S] READER
  27.641 +      [S] NEWNEWS
  27.642 +      [S] LIST ACTIVE NEWSGROUPS
  27.643 +      [S] .
  27.644 +      [C] OVER
  27.645 +      [S] 500 Unknown command
  27.646 +
  27.647 +   Example of an unsupported variant:
  27.648 +
  27.649 +      [C] MODE POSTER
  27.650 +      [S] 501 Unknown MODE option
  27.651 +
  27.652 +   Example of a syntax error:
  27.653 +
  27.654 +      [C] ARTICLE a.message.id@no.angle.brackets
  27.655 +      [S] 501 Syntax error
  27.656 +
  27.657 +   Example of an overlong command line:
  27.658 +
  27.659 +      [C] HEAD 53 54 55
  27.660 +      [S] 501 Too many arguments
  27.661 +
  27.662 +   Example of a bad wildmat:
  27.663 +
  27.664 +      [C] LIST ACTIVE u[ks].*
  27.665 +      [S] 501 Syntax error
  27.666 +
  27.667 +
  27.668 +
  27.669 +
  27.670 +
  27.671 +
  27.672 +Feather                     Standards Track                    [Page 12]
  27.673 +
  27.674 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.675 +
  27.676 +
  27.677 +   Example of a base64-encoding error (the second argument is meant to
  27.678 +   be base64 encoded):
  27.679 +
  27.680 +      [C] XENCRYPT RSA abcd=efg
  27.681 +      [S] 504 Base64 encoding error
  27.682 +
  27.683 +   Example of an attempt to access a facility not available to this
  27.684 +   connection:
  27.685 +
  27.686 +      [C] MODE READER
  27.687 +      [S] 200 Reader mode, posting permitted
  27.688 +      [C] IHAVE <i.am.an.article.you.will.want@example.com>
  27.689 +      [S] 500 Permission denied
  27.690 +
  27.691 +   Example of an attempt to access a facility requiring authentication:
  27.692 +
  27.693 +      [C] GROUP secret.group
  27.694 +      [S] 480 Permission denied
  27.695 +
  27.696 +   Example of a successful attempt following such authentication:
  27.697 +
  27.698 +      [C] XSECRET fred flintstone
  27.699 +      [S] 290 Password for fred accepted
  27.700 +      [C] GROUP secret.group
  27.701 +      [S] 211 5 1 20 secret.group selected
  27.702 +
  27.703 +   Example of an attempt to access a facility requiring privacy:
  27.704 +
  27.705 +      [C] GROUP secret.group
  27.706 +      [S] 483 Secure connection required
  27.707 +      [C] XENCRYPT
  27.708 +      [Client and server negotiate encryption on the link]
  27.709 +      [S] 283 Encrypted link established
  27.710 +      [C] GROUP secret.group
  27.711 +      [S] 211 5 1 20 secret.group selected
  27.712 +
  27.713 +   Example of a need to change mode before a facility is used:
  27.714 +
  27.715 +      [C] GROUP binary.group
  27.716 +      [S] 401 XHOST Not on this virtual host
  27.717 +      [C] XHOST binary.news.example.org
  27.718 +      [S] 290 binary.news.example.org virtual host selected
  27.719 +      [C] GROUP binary.group
  27.720 +      [S] 211 5 1 77 binary.group selected
  27.721 +
  27.722 +
  27.723 +
  27.724 +
  27.725 +
  27.726 +
  27.727 +
  27.728 +Feather                     Standards Track                    [Page 13]
  27.729 +
  27.730 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.731 +
  27.732 +
  27.733 +   Example of a temporary failure:
  27.734 +
  27.735 +      [C] GROUP archive.local
  27.736 +      [S] 403 Archive server temporarily offline
  27.737 +
  27.738 +   Example of the server needing to close down immediately:
  27.739 +
  27.740 +      [C] ARTICLE 123
  27.741 +      [S] 400 Power supply failed, running on UPS
  27.742 +      [Server closes connection.]
  27.743 +
  27.744 +3.3.  Capabilities and Extensions
  27.745 +
  27.746 +   Not all NNTP servers provide exactly the same facilities, both
  27.747 +   because this specification allows variation and because servers may
  27.748 +   provide extensions.  A set of facilities that are related are called
  27.749 +   a "capability".  This specification provides a way to determine what
  27.750 +   capabilities are available, includes a list of standard capabilities,
  27.751 +   and includes a mechanism (the extension mechanism) for defining new
  27.752 +   capabilities.
  27.753 +
  27.754 +3.3.1.  Capability Descriptions
  27.755 +
  27.756 +   A client can determine the available capabilities of the server by
  27.757 +   using the CAPABILITIES command (Section 5.2).  This returns a
  27.758 +   capability list, which is a list of capability lines.  Each line
  27.759 +   describes one available capability.
  27.760 +
  27.761 +   Each capability line consists of one or more tokens, which MUST be
  27.762 +   separated by one or more space or TAB characters.  A token is a
  27.763 +   string of 1 or more printable UTF-8 characters (that is, either
  27.764 +   printable US-ASCII characters or any UTF-8 sequence outside the US-
  27.765 +   ASCII range, but not space or TAB).  Unless stated otherwise, tokens
  27.766 +   are case insensitive.  Each capability line consists of the
  27.767 +   following:
  27.768 +
  27.769 +   o  The capability label, which is a keyword indicating the
  27.770 +      capability.  A capability label may be defined by this
  27.771 +      specification or a successor, or by an extension.
  27.772 +
  27.773 +   o  The label is then followed by zero or more tokens, which are
  27.774 +      arguments of the capability.  The form and meaning of these tokens
  27.775 +      is specific to each capability.
  27.776 +
  27.777 +   The server MUST ensure that the capability list accurately reflects
  27.778 +   the capabilities (including extensions) currently available.  If a
  27.779 +   capability is only available with the server in a certain state (for
  27.780 +   example, only after authentication), the list MUST only include the
  27.781 +
  27.782 +
  27.783 +
  27.784 +Feather                     Standards Track                    [Page 14]
  27.785 +
  27.786 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.787 +
  27.788 +
  27.789 +   capability label when the server is in that state.  Similarly, if
  27.790 +   only some of the commands in an extension will be available, or if
  27.791 +   the behaviour of the extension will change in some other manner,
  27.792 +   according to the state of the server, this MUST be indicated by
  27.793 +   different arguments in the capability line.
  27.794 +
  27.795 +   Note that a capability line can only begin with a letter.  Lines
  27.796 +   beginning with other characters are reserved for future versions of
  27.797 +   this specification.  In order to interoperate with such versions,
  27.798 +   clients MUST be prepared to receive lines beginning with other
  27.799 +   characters and MUST ignore any they do not understand.
  27.800 +
  27.801 +3.3.2.  Standard Capabilities
  27.802 +
  27.803 +   The following capabilities are defined by this specification.
  27.804 +
  27.805 +   VERSION
  27.806 +      This capability MUST be advertised by all servers and MUST be the
  27.807 +      first capability in the capability list; it indicates the
  27.808 +      version(s) of NNTP that the server supports.  There must be at
  27.809 +      least one argument; each argument is a decimal number and MUST NOT
  27.810 +      have a leading zero.  Version numbers are assigned only in RFCs
  27.811 +      that update or replace this specification; servers MUST NOT create
  27.812 +      their own version numbers.
  27.813 +
  27.814 +      The version number of this specification is 2.
  27.815 +
  27.816 +   READER
  27.817 +      This capability indicates that the server implements the various
  27.818 +      commands useful for reading clients.
  27.819 +
  27.820 +   IHAVE
  27.821 +      This capability indicates that the server implements the IHAVE
  27.822 +      command.
  27.823 +
  27.824 +   POST
  27.825 +      This capability indicates that the server implements the POST
  27.826 +      command.
  27.827 +
  27.828 +   NEWNEWS
  27.829 +      This capability indicates that the server implements the NEWNEWS
  27.830 +      command.
  27.831 +
  27.832 +   HDR
  27.833 +      This capability indicates that the server implements the header
  27.834 +      access commands (HDR and LIST HEADERS).
  27.835 +
  27.836 +
  27.837 +
  27.838 +
  27.839 +
  27.840 +Feather                     Standards Track                    [Page 15]
  27.841 +
  27.842 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.843 +
  27.844 +
  27.845 +   OVER
  27.846 +      This capability indicates that the server implements the overview
  27.847 +      access commands (OVER and LIST OVERVIEW.FMT).  If and only if the
  27.848 +      server supports the message-id form of the OVER command, there
  27.849 +      must be a single argument MSGID.
  27.850 +
  27.851 +   LIST
  27.852 +      This capability indicates that the server implements at least one
  27.853 +      variant of the LIST command.  There MUST be one argument for each
  27.854 +      variant of the LIST command supported by the server, giving the
  27.855 +      keyword for that variant.
  27.856 +
  27.857 +   IMPLEMENTATION
  27.858 +      This capability MAY be provided by a server.  If so, the arguments
  27.859 +      SHOULD be used to provide information such as the server software
  27.860 +      name and version number.  The client MUST NOT use this line to
  27.861 +      determine capabilities of the server.  (While servers often
  27.862 +      provide this information in the initial greeting, clients need to
  27.863 +      guess whether this is the case; this capability makes it clear
  27.864 +      what the information is.)
  27.865 +
  27.866 +   MODE-READER
  27.867 +      This capability indicates that the server is mode-switching
  27.868 +      (Section 3.4.2) and that the MODE READER command needs to be used
  27.869 +      to enable the READER capability.
  27.870 +
  27.871 +3.3.3.  Extensions
  27.872 +
  27.873 +   Although NNTP is widely and robustly deployed, some parts of the
  27.874 +   Internet community might wish to extend the NNTP service.  It must be
  27.875 +   emphasized that any extension to NNTP should not be considered
  27.876 +   lightly.  NNTP's strength comes primarily from its simplicity.
  27.877 +   Experience with many protocols has shown that:
  27.878 +
  27.879 +      Protocols with few options tend towards ubiquity, whilst protocols
  27.880 +      with many options tend towards obscurity.
  27.881 +
  27.882 +   This means that each and every extension, regardless of its benefits,
  27.883 +   must be carefully scrutinized with respect to its implementation,
  27.884 +   deployment, and interoperability costs.  In many cases, the cost of
  27.885 +   extending the NNTP service will likely outweigh the benefit.
  27.886 +
  27.887 +   An extension is a package of associated facilities, often but not
  27.888 +   always including one or more new commands.  Each extension MUST
  27.889 +   define at least one new capability label (this will often, but need
  27.890 +   not, be the name of one of these new commands).  While any additional
  27.891 +   capability information can normally be specified using arguments to
  27.892 +
  27.893 +
  27.894 +
  27.895 +
  27.896 +Feather                     Standards Track                    [Page 16]
  27.897 +
  27.898 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.899 +
  27.900 +
  27.901 +   that label, an extension MAY define more than one capability label.
  27.902 +   However, this SHOULD be limited to exceptional circumstances.
  27.903 +
  27.904 +   An extension is either a private extension, or its capabilities are
  27.905 +   included in the IANA registry of capabilities (see Section 3.3.4) and
  27.906 +   it is defined in an RFC (in which case it is a "registered
  27.907 +   extension").  Such RFCs either must be on the standards track or must
  27.908 +   define an IESG-approved experimental protocol.
  27.909 +
  27.910 +   The definition of an extension must include the following:
  27.911 +
  27.912 +   o  a descriptive name for the extension.
  27.913 +
  27.914 +   o  the capability label or labels defined by the extension (the
  27.915 +      capability label of a registered extension MUST NOT begin with
  27.916 +      "X").
  27.917 +
  27.918 +   o  The syntax, values, and meanings of any arguments for each
  27.919 +      capability label defined by the extension.
  27.920 +
  27.921 +   o  Any new NNTP commands associated with the extension (the names of
  27.922 +      commands associated with registered extensions MUST NOT begin with
  27.923 +      "X").
  27.924 +
  27.925 +   o  The syntax and possible values of arguments associated with the
  27.926 +      new NNTP commands.
  27.927 +
  27.928 +   o  The response codes and possible values of arguments for the
  27.929 +      responses of the new NNTP commands.
  27.930 +
  27.931 +   o  Any new arguments the extension associates with any other
  27.932 +      pre-existing NNTP commands.
  27.933 +
  27.934 +   o  Any increase in the maximum length of commands and initial
  27.935 +      response lines over the value specified in this document.
  27.936 +
  27.937 +   o  A specific statement about the effect on pipelining that this
  27.938 +      extension may have (if any).
  27.939 +
  27.940 +   o  A specific statement about the circumstances when use of this
  27.941 +      extension can alter the contents of the capabilities list (other
  27.942 +      than the new capability labels it defines).
  27.943 +
  27.944 +   o  A specific statement about the circumstances under which the
  27.945 +      extension can cause any pre-existing command to produce a 401,
  27.946 +      480, or 483 response.
  27.947 +
  27.948 +
  27.949 +
  27.950 +
  27.951 +
  27.952 +Feather                     Standards Track                    [Page 17]
  27.953 +
  27.954 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
  27.955 +
  27.956 +
  27.957 +   o  A description of how the use of MODE READER on a mode-switching
  27.958 +      server interacts with the extension.
  27.959 +
  27.960 +   o  A description of how support for the extension affects the
  27.961 +      behaviour of a server and NNTP client in any other manner not
  27.962 +      outlined above.
  27.963 +
  27.964 +   o  Formal syntax as described in Section 9.9.
  27.965 +
  27.966 +   A private extension MAY or MAY NOT be included in the capabilities
  27.967 +   list.  If it is, the capability label MUST begin with "X".  A server
  27.968 +   MAY provide additional keywords (for new commands and also for new
  27.969 +   variants of existing commands) as part of a private extension.  To
  27.970 +   avoid the risk of a clash with a future registered extension, these
  27.971 +   keywords SHOULD begin with "X".
  27.972 +
  27.973 +   If the server advertises a capability defined by a registered
  27.974 +   extension, it MUST implement the extension so as to fully conform
  27.975 +   with the specification (for example, it MUST implement all the
  27.976 +   commands that the extension describes as mandatory).  If it does not
  27.977 +   implement the extension as specified, it MUST NOT list the extension
  27.978 +   in the capabilities list under its registered name.  In that case, it
  27.979 +   MAY, but SHOULD NOT, provide a private extension (not listed, or
  27.980 +   listed with a different name) that implements part of the extension
  27.981 +   or implements the commands of the extension with a different meaning.
  27.982 +
  27.983 +   A server MUST NOT send different response codes to basic NNTP
  27.984 +   commands documented here or to commands documented in registered
  27.985 +   extensions in response to the availability or use of a private
  27.986 +   extension.
  27.987 +
  27.988 +3.3.4.  Initial IANA Register
  27.989 +
  27.990 +   IANA will maintain a registry of NNTP capability labels.  All
  27.991 +   capability labels in the registry MUST be keywords and MUST NOT begin
  27.992 +   with X.
  27.993 +
  27.994 +
  27.995 +
  27.996 +
  27.997 +
  27.998 +
  27.999 +
 27.1000 +
 27.1001 +
 27.1002 +
 27.1003 +
 27.1004 +
 27.1005 +
 27.1006 +
 27.1007 +
 27.1008 +Feather                     Standards Track                    [Page 18]
 27.1009 +
 27.1010 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1011 +
 27.1012 +
 27.1013 +   The initial content of the registry consists of these entries:
 27.1014 +
 27.1015 +   +-------------------+--------------------------+--------------------+
 27.1016 +   | Label             | Meaning                  | Definition         |
 27.1017 +   +-------------------+--------------------------+--------------------+
 27.1018 +   | AUTHINFO          | Authentication           | [NNTP-AUTH]        |
 27.1019 +   |                   |                          |                    |
 27.1020 +   | HDR               | Batched header retrieval | Section 3.3.2,     |
 27.1021 +   |                   |                          | Section 8.5, and   |
 27.1022 +   |                   |                          | Section 8.6        |
 27.1023 +   |                   |                          |                    |
 27.1024 +   | IHAVE             | IHAVE command available  | Section 3.3.2 and  |
 27.1025 +   |                   |                          | Section 6.3.2      |
 27.1026 +   |                   |                          |                    |
 27.1027 +   | IMPLEMENTATION    | Server                   | Section 3.3.2      |
 27.1028 +   |                   | implementation-specific  |                    |
 27.1029 +   |                   | information              |                    |
 27.1030 +   |                   |                          |                    |
 27.1031 +   | LIST              | LIST command variants    | Section 3.3.2 and  |
 27.1032 +   |                   |                          | Section 7.6.1      |
 27.1033 +   |                   |                          |                    |
 27.1034 +   | MODE-READER       | Mode-switching server    | Section 3.4.2      |
 27.1035 +   |                   | and MODE READER command  |                    |
 27.1036 +   |                   | available                |                    |
 27.1037 +   |                   |                          |                    |
 27.1038 +   | NEWNEWS           | NEWNEWS command          | Section 3.3.2 and  |
 27.1039 +   |                   | available                | Section 7.4        |
 27.1040 +   |                   |                          |                    |
 27.1041 +   | OVER              | Overview support         | Section 3.3.2,     |
 27.1042 +   |                   |                          | Section 8.3, and   |
 27.1043 +   |                   |                          | Section 8.4        |
 27.1044 +   |                   |                          |                    |
 27.1045 +   | POST              | POST command available   | Section 3.3.2 and  |
 27.1046 +   |                   |                          | Section 6.3.1      |
 27.1047 +   |                   |                          |                    |
 27.1048 +   | READER            | Reader commands          | Section 3.3.2      |
 27.1049 +   |                   | available                |                    |
 27.1050 +   |                   |                          |                    |
 27.1051 +   | SASL              | Supported SASL           | [NNTP-AUTH]        |
 27.1052 +   |                   | mechanisms               |                    |
 27.1053 +   |                   |                          |                    |
 27.1054 +   | STARTTLS          | Transport layer security | [NNTP-TLS]         |
 27.1055 +   |                   |                          |                    |
 27.1056 +   | STREAMING         | Streaming feeds          | [NNTP-STREAM]      |
 27.1057 +   |                   |                          |                    |
 27.1058 +   | VERSION           | Supported NNTP versions  | Section 3.3.2      |
 27.1059 +   +-------------------+--------------------------+--------------------+
 27.1060 +
 27.1061 +
 27.1062 +
 27.1063 +
 27.1064 +Feather                     Standards Track                    [Page 19]
 27.1065 +
 27.1066 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1067 +
 27.1068 +
 27.1069 +3.4.  Mandatory and Optional Commands
 27.1070 +
 27.1071 +   For a number of reasons, not all the commands in this specification
 27.1072 +   are mandatory.  However, it is equally undesirable for every command
 27.1073 +   to be optional, since this means that a client will have no idea what
 27.1074 +   facilities are available.  Therefore, as a compromise, some of the
 27.1075 +   commands in this specification are mandatory (they must be supported
 27.1076 +   by all servers) while the remainder are not.  The latter are then
 27.1077 +   subdivided into bundles, each indicated by a single capability label.
 27.1078 +
 27.1079 +   o  If the label is included in the capability list returned by the
 27.1080 +      server, the server MUST support all commands in that bundle.
 27.1081 +
 27.1082 +   o  If the label is not included, the server MAY support none or some
 27.1083 +      of the commands but SHOULD NOT support all of them.  In general,
 27.1084 +      there will be no way for a client to determine which commands are
 27.1085 +      supported without trying them.
 27.1086 +
 27.1087 +   The bundles have been chosen to provide useful functionality, and
 27.1088 +   therefore server authors are discouraged from implementing only part
 27.1089 +   of a bundle.
 27.1090 +
 27.1091 +   The description of each command will either indicate that it is
 27.1092 +   mandatory, or will give, using the term "indicating capability", the
 27.1093 +   capability label indicating whether the bundle including this command
 27.1094 +   is available.
 27.1095 +
 27.1096 +   Where a server does not implement a command, it MUST always generate
 27.1097 +   a 500 generic response code (or a 501 generic response code in the
 27.1098 +   case of a variant of a command depending on a second keyword where
 27.1099 +   the base command is recognised).  Otherwise, the command MUST be
 27.1100 +   fully implemented as specified; a server MUST NOT only partially
 27.1101 +   implement any of the commands in this specification.  (Client authors
 27.1102 +   should note that some servers not conforming to this specification
 27.1103 +   will return a 502 generic response code to some commands that are not
 27.1104 +   implemented.)
 27.1105 +
 27.1106 +   Note: some commands have cases that require other commands to be used
 27.1107 +   first.  If the former command is implemented but the latter is not,
 27.1108 +   the former MUST still generate the relevant specific response code.
 27.1109 +   For example, if ARTICLE (Section 6.2.1) is implemented but GROUP
 27.1110 +   (Section 6.1.1) is not, the correct response to "ARTICLE 1234"
 27.1111 +   remains 412.
 27.1112 +
 27.1113 +
 27.1114 +
 27.1115 +
 27.1116 +
 27.1117 +
 27.1118 +
 27.1119 +
 27.1120 +Feather                     Standards Track                    [Page 20]
 27.1121 +
 27.1122 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1123 +
 27.1124 +
 27.1125 +3.4.1.  Reading and Transit Servers
 27.1126 +
 27.1127 +   NNTP is traditionally used in two different ways.  The first use is
 27.1128 +   "reading", where the client fetches articles from a large store
 27.1129 +   maintained by the server for immediate or later presentation to a
 27.1130 +   user and sends articles created by that user back to the server (an
 27.1131 +   action called "posting") to be stored and distributed to other stores
 27.1132 +   and users.  The second use is for the bulk transfer of articles from
 27.1133 +   one store to another.  Since the hosts making this transfer tend to
 27.1134 +   be peers in a network that transmit articles among one another, and
 27.1135 +   not end-user systems, this process is called "peering" or "transit".
 27.1136 +   (Even so, one host is still the client and the other is the server).
 27.1137 +
 27.1138 +   In practice, these two uses are so different that some server
 27.1139 +   implementations are optimised for reading or for transit and, as a
 27.1140 +   result, do not offer the other facility or only offer limited
 27.1141 +   features.  Other implementations are more general and offer both.
 27.1142 +   This specification allows for this by bundling the relevant commands
 27.1143 +   accordingly: the IHAVE command is designed for transit, while the
 27.1144 +   commands indicated by the READER capability are designed for reading
 27.1145 +   clients.
 27.1146 +
 27.1147 +   Except as an effect of the MODE READER command (Section 5.3) on a
 27.1148 +   mode-switching server, once a server advertises either or both of the
 27.1149 +   IHAVE or READER capabilities, it MUST continue to advertise them for
 27.1150 +   the entire session.
 27.1151 +
 27.1152 +   A server MAY provide different modes of behaviour (transit, reader,
 27.1153 +   or a combination) to different client connections and MAY use
 27.1154 +   external information, such as the IP address of the client, to
 27.1155 +   determine which mode to provide to any given connection.
 27.1156 +
 27.1157 +   The official TCP port for the NNTP service is 119.  However, if a
 27.1158 +   host wishes to offer separate servers for transit and reading
 27.1159 +   clients, port 433 SHOULD be used for the transit server and 119 for
 27.1160 +   the reading server.
 27.1161 +
 27.1162 +3.4.2.  Mode Switching
 27.1163 +
 27.1164 +   An implementation MAY, but SHOULD NOT, provide both transit and
 27.1165 +   reader facilities on the same server but require the client to select
 27.1166 +   which it wishes to use.  Such an arrangement is called a
 27.1167 +   "mode-switching" server.
 27.1168 +
 27.1169 +
 27.1170 +
 27.1171 +
 27.1172 +
 27.1173 +
 27.1174 +
 27.1175 +
 27.1176 +Feather                     Standards Track                    [Page 21]
 27.1177 +
 27.1178 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1179 +
 27.1180 +
 27.1181 +   A mode-switching server has two modes:
 27.1182 +
 27.1183 +   o  Transit mode, which applies after the initial connection.
 27.1184 +
 27.1185 +      *  It MUST advertise the MODE-READER capability.
 27.1186 +
 27.1187 +      *  It MUST NOT advertise the READER capability.
 27.1188 +
 27.1189 +      However, the server MAY cease to advertise the MODE-READER
 27.1190 +      capability after the client uses any command except CAPABILITIES.
 27.1191 +
 27.1192 +   o  Reading mode, after a successful MODE READER command (see Section
 27.1193 +      5.3).
 27.1194 +
 27.1195 +      *  It MUST NOT advertise the MODE-READER capability.
 27.1196 +
 27.1197 +      *  It MUST advertise the READER capability.
 27.1198 +
 27.1199 +      *  It MAY NOT advertise the IHAVE capability, even if it was
 27.1200 +         advertising it in transit mode.
 27.1201 +
 27.1202 +   A client SHOULD only issue a MODE READER command to a server if it is
 27.1203 +   advertising the MODE-READER capability.  If the server does not
 27.1204 +   support CAPABILITIES (and therefore does not conform to this
 27.1205 +   specification), the client MAY use the following heuristic:
 27.1206 +
 27.1207 +   o  If the client wishes to use any "reader" commands, it SHOULD use
 27.1208 +      the MODE READER command immediately after the initial connection.
 27.1209 +
 27.1210 +   o  Otherwise, it SHOULD NOT use the MODE READER command.
 27.1211 +
 27.1212 +   In each case, it should be prepared for some commands to be
 27.1213 +   unavailable that would have been available if it had made the other
 27.1214 +   choice.
 27.1215 +
 27.1216 +3.5.  Pipelining
 27.1217 +
 27.1218 +   NNTP is designed to operate over a reliable bi-directional
 27.1219 +   connection, such as TCP.  Therefore, if a command does not depend on
 27.1220 +   the response to the previous one, it should not matter if it is sent
 27.1221 +   before that response is received.  Doing this is called "pipelining".
 27.1222 +   However, certain server implementations throw away all text received
 27.1223 +   from the client following certain commands before sending their
 27.1224 +   response.  If this happens, pipelining will be affected because one
 27.1225 +   or more commands will have been ignored or misinterpreted, and the
 27.1226 +   client will be matching the wrong responses to each command.  Since
 27.1227 +   there are significant benefits to pipelining, but also circumstances
 27.1228 +   where it is reasonable or common for servers to behave in the above
 27.1229 +
 27.1230 +
 27.1231 +
 27.1232 +Feather                     Standards Track                    [Page 22]
 27.1233 +
 27.1234 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1235 +
 27.1236 +
 27.1237 +   manner, this document puts certain requirements on both clients and
 27.1238 +   servers.
 27.1239 +
 27.1240 +   Except where stated otherwise, a client MAY use pipelining.  That is,
 27.1241 +   it may send a command before receiving the response for the previous
 27.1242 +   command.  The server MUST allow pipelining and MUST NOT throw away
 27.1243 +   any text received after a command.  Irrespective of whether
 27.1244 +   pipelining is used, the server MUST process commands in the order
 27.1245 +   they are sent.
 27.1246 +
 27.1247 +   If the specific description of a command says it "MUST NOT be
 27.1248 +   pipelined", that command MUST end any pipeline of commands.  That is,
 27.1249 +   the client MUST NOT send any following command until it receives the
 27.1250 +   CRLF at the end of the response from the command.  The server MAY
 27.1251 +   ignore any data received after the command and before the CRLF at the
 27.1252 +   end of the response is sent to the client.
 27.1253 +
 27.1254 +   The initial connection must not be part of a pipeline; that is, the
 27.1255 +   client MUST NOT send any command until it receives the CRLF at the
 27.1256 +   end of the greeting.
 27.1257 +
 27.1258 +   If the client uses blocking system calls to send commands, it MUST
 27.1259 +   ensure that the amount of text sent in pipelining does not cause a
 27.1260 +   deadlock between transmission and reception.  The amount of text
 27.1261 +   involved will depend on window sizes in the transmission layer;
 27.1262 +   typically, it is 4k octets for TCP.  (Since the server only sends
 27.1263 +   data in response to commands from the client, the converse problem
 27.1264 +   does not occur.)
 27.1265 +
 27.1266 +3.5.1.  Examples
 27.1267 +
 27.1268 +   Example of correct use of pipelining:
 27.1269 +
 27.1270 +      [C] GROUP misc.test
 27.1271 +      [C] STAT
 27.1272 +      [C] NEXT
 27.1273 +      [S] 211 1234 3000234 3002322 misc.test
 27.1274 +      [S] 223 3000234 <45223423@example.com> retrieved
 27.1275 +      [S] 223 3000237 <668929@example.org> retrieved
 27.1276 +
 27.1277 +   Example of incorrect use of pipelining (the MODE READER command may
 27.1278 +   not be pipelined):
 27.1279 +
 27.1280 +      [C] MODE READER
 27.1281 +      [C] DATE
 27.1282 +      [C] NEXT
 27.1283 +      [S] 200 Server ready, posting allowed
 27.1284 +      [S] 223 3000237 <668929@example.org> retrieved
 27.1285 +
 27.1286 +
 27.1287 +
 27.1288 +Feather                     Standards Track                    [Page 23]
 27.1289 +
 27.1290 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1291 +
 27.1292 +
 27.1293 +   The DATE command has been thrown away by the server, so there is no
 27.1294 +   111 response to match it.
 27.1295 +
 27.1296 +3.6.  Articles
 27.1297 +
 27.1298 +   NNTP is intended to transfer articles between clients and servers.
 27.1299 +   For the purposes of this specification, articles are required to
 27.1300 +   conform to the rules in this section, and clients and servers MUST
 27.1301 +   correctly process any article received from the other that does so.
 27.1302 +   Note that this requirement applies only to the contents of
 27.1303 +   communications over NNTP; it does not prevent the client or server
 27.1304 +   from subsequently rejecting an article for reasons of local policy.
 27.1305 +   Also see Appendix A for further restrictions on the format of
 27.1306 +   articles in some uses of NNTP.
 27.1307 +
 27.1308 +   An article consists of two parts: the headers and the body.  They are
 27.1309 +   separated by a single empty line, or in other words by two
 27.1310 +   consecutive CRLF pairs (if there is more than one empty line, the
 27.1311 +   second and subsequent ones are part of the body).  In order to meet
 27.1312 +   the general requirements of NNTP, an article MUST NOT include the
 27.1313 +   octet NUL, MUST NOT contain the octets LF and CR other than as part
 27.1314 +   of a CRLF pair, and MUST end with a CRLF pair.  This specification
 27.1315 +   puts no further restrictions on the body; in particular, it MAY be
 27.1316 +   empty.
 27.1317 +
 27.1318 +   The headers of an article consist of one or more header lines.  Each
 27.1319 +   header line consists of a header name, a colon, a space, the header
 27.1320 +   content, and a CRLF, in that order.  The name consists of one or more
 27.1321 +   printable US-ASCII characters other than colon and, for the purposes
 27.1322 +   of this specification, is not case sensitive.  There MAY be more than
 27.1323 +   one header line with the same name.  The content MUST NOT contain
 27.1324 +   CRLF; it MAY be empty.  A header may be "folded"; that is, a CRLF
 27.1325 +   pair may be placed before any TAB or space in the line.  There MUST
 27.1326 +   still be some other octet between any two CRLF pairs in a header
 27.1327 +   line.  (Note that folding means that the header line occupies more
 27.1328 +   than one line when displayed or transmitted; nevertheless, it is
 27.1329 +   still referred to as "a" header line.)  The presence or absence of
 27.1330 +   folding does not affect the meaning of the header line; that is, the
 27.1331 +   CRLF pairs introduced by folding are not considered part of the
 27.1332 +   header content.  Header lines SHOULD NOT be folded before the space
 27.1333 +   after the colon that follows the header name and SHOULD include at
 27.1334 +   least one octet other than %x09 or %x20 between CRLF pairs.  However,
 27.1335 +   if an article that fails to satisfy this requirement has been
 27.1336 +   received from elsewhere, clients and servers MAY transfer it to each
 27.1337 +   other without re-folding it.
 27.1338 +
 27.1339 +
 27.1340 +
 27.1341 +
 27.1342 +
 27.1343 +
 27.1344 +Feather                     Standards Track                    [Page 24]
 27.1345 +
 27.1346 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1347 +
 27.1348 +
 27.1349 +   The content of a header SHOULD be in UTF-8.  However, if an
 27.1350 +   implementation receives an article from elsewhere that uses octets in
 27.1351 +   the range 128 to 255 in some other manner, it MAY pass it to a client
 27.1352 +   or server without modification.  Therefore, implementations MUST be
 27.1353 +   prepared to receive such headers, and data derived from them (e.g.,
 27.1354 +   in the responses from the OVER command, Section 8.3), and MUST NOT
 27.1355 +   assume that they are always UTF-8.  Any external processing of those
 27.1356 +   headers, including identifying the encoding used, is outside the
 27.1357 +   scope of this document.
 27.1358 +
 27.1359 +   Each article MUST have a unique message-id; two articles offered by
 27.1360 +   an NNTP server MUST NOT have the same message-id.  For the purposes
 27.1361 +   of this specification, message-ids are opaque strings that MUST meet
 27.1362 +   the following requirements:
 27.1363 +
 27.1364 +   o  A message-id MUST begin with "<", end with ">", and MUST NOT
 27.1365 +      contain the latter except at the end.
 27.1366 +
 27.1367 +   o  A message-id MUST be between 3 and 250 octets in length.
 27.1368 +
 27.1369 +   o  A message-id MUST NOT contain octets other than printable US-ASCII
 27.1370 +      characters.
 27.1371 +
 27.1372 +   Two message-ids are the same if and only if they consist of the same
 27.1373 +   sequence of octets.
 27.1374 +
 27.1375 +   This specification does not describe how the message-id of an article
 27.1376 +   is determined.  If the server does not have any way to determine a
 27.1377 +   message-id from the article itself, it MUST synthesize one (this
 27.1378 +   specification does not require that the article be changed as a
 27.1379 +   result).  See also Appendix A.2.
 27.1380 +
 27.1381 +4.  The WILDMAT Format
 27.1382 +
 27.1383 +   The WILDMAT format described here is based on the version first
 27.1384 +   developed by Rich Salz [SALZ1992], which was in turn derived from the
 27.1385 +   format used in the UNIX "find" command to articulate file names.  It
 27.1386 +   was developed to provide a uniform mechanism for matching patterns in
 27.1387 +   the same manner that the UNIX shell matches filenames.
 27.1388 +
 27.1389 +
 27.1390 +
 27.1391 +
 27.1392 +
 27.1393 +
 27.1394 +
 27.1395 +
 27.1396 +
 27.1397 +
 27.1398 +
 27.1399 +
 27.1400 +Feather                     Standards Track                    [Page 25]
 27.1401 +
 27.1402 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1403 +
 27.1404 +
 27.1405 +4.1.  Wildmat Syntax
 27.1406 +
 27.1407 +   A wildmat is described by the following ABNF [RFC4234] syntax, which
 27.1408 +   is an extract of that in Section 9.8.
 27.1409 +
 27.1410 +     wildmat = wildmat-pattern *("," ["!"] wildmat-pattern)
 27.1411 +     wildmat-pattern = 1*wildmat-item
 27.1412 +     wildmat-item = wildmat-exact / wildmat-wild
 27.1413 +     wildmat-exact = %x22-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E /
 27.1414 +          UTF8-non-ascii ; exclude ! * , ? [ \ ]
 27.1415 +     wildmat-wild = "*" / "?"
 27.1416 +
 27.1417 +   Note: the characters ",", "\", "[", and "]" are not allowed in
 27.1418 +   wildmats, while * and ? are always wildcards.  This should not be a
 27.1419 +   problem, since these characters cannot occur in newsgroup names,
 27.1420 +   which is the only current use of wildmats.  Backslash is commonly
 27.1421 +   used to suppress the special meaning of characters, whereas brackets
 27.1422 +   are used to introduce sets.  However, these usages are not universal,
 27.1423 +   and interpretation of these characters in the context of UTF-8
 27.1424 +   strings is potentially complex and differs from existing practice, so
 27.1425 +   they were omitted from this specification.  A future extension to
 27.1426 +   this specification may provide semantics for these characters.
 27.1427 +
 27.1428 +4.2.  Wildmat Semantics
 27.1429 +
 27.1430 +   A wildmat is tested against a string and either matches or does not
 27.1431 +   match.  To do this, each constituent <wildmat-pattern> is matched
 27.1432 +   against the string, and the rightmost pattern that matches is
 27.1433 +   identified.  If that <wildmat-pattern> is not preceded with "!", the
 27.1434 +   whole wildmat matches.  If it is preceded by "!", or if no <wildmat-
 27.1435 +   pattern> matches, the whole wildmat does not match.
 27.1436 +
 27.1437 +   For example, consider the wildmat "a*,!*b,*c*":
 27.1438 +
 27.1439 +   o  The string "aaa" matches because the rightmost match is with "a*".
 27.1440 +
 27.1441 +   o  The string "abb" does not match because the rightmost match is
 27.1442 +      with "*b".
 27.1443 +
 27.1444 +   o  The string "ccb" matches because the rightmost match is with
 27.1445 +      "*c*".
 27.1446 +
 27.1447 +   o  The string "xxx" does not match because no <wildmat-pattern>
 27.1448 +      matches.
 27.1449 +
 27.1450 +   A <wildmat-pattern> matches a string if the string can be broken into
 27.1451 +   components, each of which matches the corresponding <wildmat-item> in
 27.1452 +   the pattern.  The matches must be in the same order, and the whole
 27.1453 +
 27.1454 +
 27.1455 +
 27.1456 +Feather                     Standards Track                    [Page 26]
 27.1457 +
 27.1458 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1459 +
 27.1460 +
 27.1461 +   string must be used in the match.  The pattern is "anchored"; that
 27.1462 +   is, the first and last characters in the string must match the first
 27.1463 +   and last item, respectively (unless that item is an asterisk matching
 27.1464 +   zero characters).
 27.1465 +
 27.1466 +   A <wildmat-exact> matches the same character (which may be more than
 27.1467 +   one octet in UTF-8).
 27.1468 +
 27.1469 +   "?" matches exactly one character (which may be more than one octet).
 27.1470 +
 27.1471 +   "*" matches zero or more characters.  It can match an empty string,
 27.1472 +   but it cannot match a subsequence of a UTF-8 sequence that is not
 27.1473 +   aligned to the character boundaries.
 27.1474 +
 27.1475 +4.3.  Extensions
 27.1476 +
 27.1477 +   An NNTP server or extension MAY extend the syntax or semantics of
 27.1478 +   wildmats provided that all wildmats that meet the requirements of
 27.1479 +   Section 4.1 have the meaning ascribed to them by Section 4.2.  Future
 27.1480 +   editions of this document may also extend wildmats.
 27.1481 +
 27.1482 +4.4.  Examples
 27.1483 +
 27.1484 +   In these examples, $ and @ are used to represent the two octets %xC2
 27.1485 +   and %xA3, respectively; $@ is thus the UTF-8 encoding for the pound
 27.1486 +   sterling symbol, shown as # in the descriptions.
 27.1487 +
 27.1488 +     Wildmat    Description of strings that match
 27.1489 +       abc      The one string "abc"
 27.1490 +       abc,def  The two strings "abc" and "def"
 27.1491 +       $@       The one character string "#"
 27.1492 +       a*       Any string that begins with "a"
 27.1493 +       a*b      Any string that begins with "a" and ends with "b"
 27.1494 +       a*,*b    Any string that begins with "a" or ends with "b"
 27.1495 +       a*,!*b   Any string that begins with "a" and does not end with
 27.1496 +                "b"
 27.1497 +     a*,!*b,c*  Any string that begins with "a" and does not end with
 27.1498 +                "b", and any string that begins with "c" no matter
 27.1499 +                what it ends with
 27.1500 +     a*,c*,!*b  Any string that begins with "a" or "c" and does not
 27.1501 +                end with "b"
 27.1502 +       ?a*      Any string with "a" as its second character
 27.1503 +       ??a*     Any string with "a" as its third character
 27.1504 +       *a?      Any string with "a" as its penultimate character
 27.1505 +       *a??     Any string with "a" as its antepenultimate character
 27.1506 +
 27.1507 +
 27.1508 +
 27.1509 +
 27.1510 +
 27.1511 +
 27.1512 +Feather                     Standards Track                    [Page 27]
 27.1513 +
 27.1514 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1515 +
 27.1516 +
 27.1517 +5.  Session Administration Commands
 27.1518 +
 27.1519 +5.1.  Initial Connection
 27.1520 +
 27.1521 +5.1.1.  Usage
 27.1522 +
 27.1523 +   This command MUST NOT be pipelined.
 27.1524 +
 27.1525 +   Responses [1]
 27.1526 +     200    Service available, posting allowed
 27.1527 +     201    Service available, posting prohibited
 27.1528 +     400    Service temporarily unavailable [2]
 27.1529 +     502    Service permanently unavailable [2]
 27.1530 +
 27.1531 +   [1] These are the only valid response codes for the initial greeting;
 27.1532 +       the server MUST not return any other generic response code.
 27.1533 +
 27.1534 +   [2] Following a 400 or 502 response, the server MUST immediately
 27.1535 +       close the connection.
 27.1536 +
 27.1537 +5.1.2.  Description
 27.1538 +
 27.1539 +   There is no command presented by the client upon initial connection
 27.1540 +   to the server.  The server MUST present an appropriate response code
 27.1541 +   as a greeting to the client.  This response informs the client
 27.1542 +   whether service is available and whether the client is permitted to
 27.1543 +   post.
 27.1544 +
 27.1545 +   If the server will accept further commands from the client including
 27.1546 +   POST, the server MUST present a 200 greeting code.  If the server
 27.1547 +   will accept further commands from the client, but the client is not
 27.1548 +   authorized to post articles using the POST command, the server MUST
 27.1549 +   present a 201 greeting code.
 27.1550 +
 27.1551 +   Otherwise, the server MUST present a 400 or 502 greeting code and
 27.1552 +   then immediately close the connection. 400 SHOULD be used if the
 27.1553 +   issue is only temporary (for example, because of load) and the client
 27.1554 +   can expect to be able to connect successfully at some point in the
 27.1555 +   future without making any changes. 502 MUST be used if the client is
 27.1556 +   not permitted under any circumstances to interact with the server,
 27.1557 +   and MAY be used if the server has insufficient information to
 27.1558 +   determine whether the issue is temporary or permanent.
 27.1559 +
 27.1560 +   Note: the distinction between the 200 and 201 response codes has
 27.1561 +   turned out in practice to be insufficient; for example, some servers
 27.1562 +   do not allow posting until the client has authenticated, while other
 27.1563 +   clients assume that a 201 response means that posting will never be
 27.1564 +   possible even after authentication.  Therefore, clients SHOULD use
 27.1565 +
 27.1566 +
 27.1567 +
 27.1568 +Feather                     Standards Track                    [Page 28]
 27.1569 +
 27.1570 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1571 +
 27.1572 +
 27.1573 +   the CAPABILITIES command (Section 5.2) rather than rely on this
 27.1574 +   response.
 27.1575 +
 27.1576 +5.1.3.  Examples
 27.1577 +
 27.1578 +   Example of a normal connection from an authorized client that then
 27.1579 +   terminates the session (see Section 5.4):
 27.1580 +
 27.1581 +      [Initial connection set-up completed.]
 27.1582 +      [S] 200 NNTP Service Ready, posting permitted
 27.1583 +      [C] QUIT
 27.1584 +      [S] 205 NNTP Service exits normally
 27.1585 +      [Server closes connection.]
 27.1586 +
 27.1587 +   Example of a normal connection from an authorized client that is not
 27.1588 +   permitted to post, which also immediately terminates the session:
 27.1589 +
 27.1590 +      [Initial connection set-up completed.]
 27.1591 +      [S] 201 NNTP Service Ready, posting prohibited
 27.1592 +      [C] QUIT
 27.1593 +      [S] 205 NNTP Service exits normally
 27.1594 +      [Server closes connection.]
 27.1595 +
 27.1596 +   Example of a normal connection from an unauthorized client:
 27.1597 +
 27.1598 +      [Initial connection set-up completed.]
 27.1599 +      [S] 502 NNTP Service permanently unavailable
 27.1600 +      [Server closes connection.]
 27.1601 +
 27.1602 +   Example of a connection from a client if the server is unable to
 27.1603 +   provide service:
 27.1604 +
 27.1605 +      [Initial connection set-up completed.]
 27.1606 +      [S] 400 NNTP Service temporarily unavailable
 27.1607 +      [Server closes connection.]
 27.1608 +
 27.1609 +5.2.  CAPABILITIES
 27.1610 +
 27.1611 +5.2.1.  Usage
 27.1612 +
 27.1613 +   This command is mandatory.
 27.1614 +
 27.1615 +   Syntax
 27.1616 +     CAPABILITIES [keyword]
 27.1617 +
 27.1618 +   Responses
 27.1619 +     101    Capability list follows (multi-line)
 27.1620 +
 27.1621 +
 27.1622 +
 27.1623 +
 27.1624 +Feather                     Standards Track                    [Page 29]
 27.1625 +
 27.1626 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1627 +
 27.1628 +
 27.1629 +   Parameters
 27.1630 +     keyword    additional feature, see description
 27.1631 +
 27.1632 +5.2.2.  Description
 27.1633 +
 27.1634 +   The CAPABILITIES command allows a client to determine the
 27.1635 +   capabilities of the server at any given time.
 27.1636 +
 27.1637 +   This command MAY be issued at any time; the server MUST NOT require
 27.1638 +   it to be issued in order to make use of any capability.  The response
 27.1639 +   generated by this command MAY change during a session because of
 27.1640 +   other state information (which, in turn, may be changed by the
 27.1641 +   effects of other commands or by external events).  An NNTP client is
 27.1642 +   only able to get the current and correct information concerning
 27.1643 +   available capabilities at any point during a session by issuing a
 27.1644 +   CAPABILITIES command at that point of that session and processing the
 27.1645 +   response.
 27.1646 +
 27.1647 +   The capability list is returned as a multi-line data block following
 27.1648 +   the 101 response code.  Each capability is described by a separate
 27.1649 +   capability line.  The server MUST NOT list the same capability twice
 27.1650 +   in the response, even with different arguments.  Except that the
 27.1651 +   VERSION capability MUST be the first line, the order in which the
 27.1652 +   capability lines appears is not significant; the server need not even
 27.1653 +   consistently return the same order.
 27.1654 +
 27.1655 +   While some capabilities are likely to be always available or never
 27.1656 +   available, others (notably extensions) will appear and disappear
 27.1657 +   depending on server state changes within the session or on external
 27.1658 +   events between sessions.  An NNTP client MAY cache the results of
 27.1659 +   this command, but MUST NOT rely on the correctness of any cached
 27.1660 +   results, whether from earlier in this session or from a previous
 27.1661 +   session, MUST cope gracefully with the cached status being out of
 27.1662 +   date, and SHOULD (if caching results) provide a way to force the
 27.1663 +   cached information to be refreshed.  Furthermore, a client MUST NOT
 27.1664 +   use cached results in relation to security, privacy, and
 27.1665 +   authentication extensions.  See Section 12.6 for further discussion
 27.1666 +   of this topic.
 27.1667 +
 27.1668 +   The keyword argument is not used by this specification.  It is
 27.1669 +   provided so that extensions or revisions to this specification can
 27.1670 +   include extra features for this command without requiring the
 27.1671 +   CAPABILITIES command to be used twice (once to determine if the extra
 27.1672 +   features are available, and a second time to make use of them).  If
 27.1673 +   the server does not recognise the argument (and it is a keyword), it
 27.1674 +   MUST respond with the 101 response code as if the argument had been
 27.1675 +   omitted.  If an argument is provided that the server does recognise,
 27.1676 +   it MAY use the 101 response code or MAY use some other response code
 27.1677 +
 27.1678 +
 27.1679 +
 27.1680 +Feather                     Standards Track                    [Page 30]
 27.1681 +
 27.1682 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1683 +
 27.1684 +
 27.1685 +   (which will be defined in the specification of that feature).  If the
 27.1686 +   argument is not a keyword, the 501 generic response code MUST be
 27.1687 +   returned.  The server MUST NOT generate any other response code to
 27.1688 +   the CAPABILITIES command.
 27.1689 +
 27.1690 +5.2.3.  Examples
 27.1691 +
 27.1692 +   Example of a minimal response (a read-only server):
 27.1693 +
 27.1694 +      [C] CAPABILITIES
 27.1695 +      [S] 101 Capability list:
 27.1696 +      [S] VERSION 2
 27.1697 +      [S] READER
 27.1698 +      [S] LIST ACTIVE NEWSGROUPS
 27.1699 +      [S] .
 27.1700 +
 27.1701 +   Example of a response from a server that has a range of facilities
 27.1702 +   and that also describes itself:
 27.1703 +
 27.1704 +      [C] CAPABILITIES
 27.1705 +      [S] 101 Capability list:
 27.1706 +      [S] VERSION 2
 27.1707 +      [S] READER
 27.1708 +      [S] IHAVE
 27.1709 +      [S] POST
 27.1710 +      [S] NEWNEWS
 27.1711 +      [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES OVERVIEW.FMT
 27.1712 +      [S] IMPLEMENTATION INN 4.2 2004-12-25
 27.1713 +      [S] OVER MSGID
 27.1714 +      [S] STREAMING
 27.1715 +      [S] XSECRET
 27.1716 +      [S] .
 27.1717 +
 27.1718 +   Example of a server that supports more than one version of NNTP:
 27.1719 +
 27.1720 +      [C] CAPABILITIES
 27.1721 +      [S] 101 Capability list:
 27.1722 +      [S] VERSION 2 3
 27.1723 +      [S] READER
 27.1724 +      [S] LIST ACTIVE NEWSGROUPS
 27.1725 +      [S] .
 27.1726 +
 27.1727 +
 27.1728 +
 27.1729 +
 27.1730 +
 27.1731 +
 27.1732 +
 27.1733 +
 27.1734 +
 27.1735 +
 27.1736 +Feather                     Standards Track                    [Page 31]
 27.1737 +
 27.1738 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1739 +
 27.1740 +
 27.1741 +   Example of a client attempting to use a feature of the CAPABILITIES
 27.1742 +   command that the server does not support:
 27.1743 +
 27.1744 +      [C] CAPABILITIES AUTOUPDATE
 27.1745 +      [S] 101 Capability list:
 27.1746 +      [S] VERSION 2
 27.1747 +      [S] READER
 27.1748 +      [S] IHAVE
 27.1749 +      [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT HEADERS
 27.1750 +      [S] OVER MSGID
 27.1751 +      [S] HDR
 27.1752 +      [S] NEWNEWS
 27.1753 +      [S] .
 27.1754 +
 27.1755 +5.3.  MODE READER
 27.1756 +
 27.1757 +5.3.1.  Usage
 27.1758 +
 27.1759 +   Indicating capability: MODE-READER
 27.1760 +
 27.1761 +   This command MUST NOT be pipelined.
 27.1762 +
 27.1763 +   Syntax
 27.1764 +     MODE READER
 27.1765 +
 27.1766 +   Responses
 27.1767 +     200    Posting allowed
 27.1768 +     201    Posting prohibited
 27.1769 +     502    Reading service permanently unavailable [1]
 27.1770 +
 27.1771 +   [1] Following a 502 response the server MUST immediately close the
 27.1772 +       connection.
 27.1773 +
 27.1774 +5.3.2.  Description
 27.1775 +
 27.1776 +   The MODE READER command instructs a mode-switching server to switch
 27.1777 +   modes, as described in Section 3.4.2.
 27.1778 +
 27.1779 +   If the server is mode-switching, it switches from its transit mode to
 27.1780 +   its reader mode, indicating this by changing the capability list
 27.1781 +   accordingly.  It MUST then return a 200 or 201 response with the same
 27.1782 +   meaning as for the initial greeting (as described in Section 5.1.1).
 27.1783 +   Note that the response need not be the same as that presented during
 27.1784 +   the initial greeting.  The client MUST NOT issue MODE READER more
 27.1785 +   than once in a session or after any security or privacy commands are
 27.1786 +   issued.  When the MODE READER command is issued, the server MAY reset
 27.1787 +   its state to that immediately after the initial connection before
 27.1788 +   switching mode.
 27.1789 +
 27.1790 +
 27.1791 +
 27.1792 +Feather                     Standards Track                    [Page 32]
 27.1793 +
 27.1794 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1795 +
 27.1796 +
 27.1797 +   If the server is not mode-switching, then the following apply:
 27.1798 +
 27.1799 +   o  If it advertises the READER capability, it MUST return a 200 or
 27.1800 +      201 response with the same meaning as for the initial greeting; in
 27.1801 +      this case, the command MUST NOT affect the server state in any
 27.1802 +      way.
 27.1803 +
 27.1804 +   o  If it does not advertise the READER capability, it MUST return a
 27.1805 +      502 response and then immediately close the connection.
 27.1806 +
 27.1807 +5.3.3.  Examples
 27.1808 +
 27.1809 +   Example of use of the MODE READER command on a transit-only server
 27.1810 +   (which therefore does not providing reading facilities):
 27.1811 +
 27.1812 +      [C] CAPABILITIES
 27.1813 +      [S] 101 Capability list:
 27.1814 +      [S] VERSION 2
 27.1815 +      [S] IHAVE
 27.1816 +      [S] .
 27.1817 +      [C] MODE READER
 27.1818 +      [S] 502 Transit service only
 27.1819 +      [Server closes connection.]
 27.1820 +
 27.1821 +   Example of use of the MODE READER command on a server that provides
 27.1822 +   reading facilities:
 27.1823 +
 27.1824 +      [C] CAPABILITIES
 27.1825 +      [S] 101 Capability list:
 27.1826 +      [S] VERSION 2
 27.1827 +      [S] READER
 27.1828 +      [S] LIST ACTIVE NEWSGROUPS
 27.1829 +      [S] .
 27.1830 +      [C] MODE READER
 27.1831 +      [S] 200 Reader mode, posting permitted
 27.1832 +      [C] IHAVE <i.am.an.article.you.have@example.com>
 27.1833 +      [S] 500 Permission denied
 27.1834 +      [C] GROUP misc.test
 27.1835 +      [S] 211 1234 3000234 3002322 misc.test
 27.1836 +
 27.1837 +   Note that in both of these situations, the client SHOULD NOT use MODE
 27.1838 +   READER.
 27.1839 +
 27.1840 +
 27.1841 +
 27.1842 +
 27.1843 +
 27.1844 +
 27.1845 +
 27.1846 +
 27.1847 +
 27.1848 +Feather                     Standards Track                    [Page 33]
 27.1849 +
 27.1850 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1851 +
 27.1852 +
 27.1853 +   Example of use of the MODE READER command on a mode-switching server:
 27.1854 +
 27.1855 +      [C] CAPABILITIES
 27.1856 +      [S] 101 Capability list:
 27.1857 +      [S] VERSION 2
 27.1858 +      [S] IHAVE
 27.1859 +      [S] MODE-READER
 27.1860 +      [S] .
 27.1861 +      [C] MODE READER
 27.1862 +      [S] 200 Reader mode, posting permitted
 27.1863 +      [C] CAPABILITIES
 27.1864 +      [S] 101 Capability list:
 27.1865 +      [S] VERSION 2
 27.1866 +      [S] READER
 27.1867 +      [S] NEWNEWS
 27.1868 +      [S] LIST ACTIVE NEWSGROUPS
 27.1869 +      [S] STARTTLS
 27.1870 +      [S] .
 27.1871 +
 27.1872 +   In this case, the server offers (but does not require) TLS privacy in
 27.1873 +   its reading mode but not in its transit mode.
 27.1874 +
 27.1875 +   Example of use of the MODE READER command where the client is not
 27.1876 +   permitted to post:
 27.1877 +
 27.1878 +      [C] MODE READER
 27.1879 +      [S] 201 NNTP Service Ready, posting prohibited
 27.1880 +
 27.1881 +5.4.  QUIT
 27.1882 +
 27.1883 +5.4.1.  Usage
 27.1884 +
 27.1885 +   This command is mandatory.
 27.1886 +
 27.1887 +   Syntax
 27.1888 +     QUIT
 27.1889 +
 27.1890 +   Responses
 27.1891 +     205    Connection closing
 27.1892 +
 27.1893 +5.4.2.  Description
 27.1894 +
 27.1895 +   The client uses the QUIT command to terminate the session.  The
 27.1896 +   server MUST acknowledge the QUIT command and then close the
 27.1897 +   connection to the client.  This is the preferred method for a client
 27.1898 +   to indicate that it has finished all of its transactions with the
 27.1899 +   NNTP server.
 27.1900 +
 27.1901 +
 27.1902 +
 27.1903 +
 27.1904 +Feather                     Standards Track                    [Page 34]
 27.1905 +
 27.1906 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1907 +
 27.1908 +
 27.1909 +   If a client simply disconnects (or if the connection times out or
 27.1910 +   some other fault occurs), the server MUST gracefully cease its
 27.1911 +   attempts to service the client, disconnecting from its end if
 27.1912 +   necessary.
 27.1913 +
 27.1914 +   The server MUST NOT generate any response code to the QUIT command
 27.1915 +   other than 205 or, if any arguments are provided, 501.
 27.1916 +
 27.1917 +5.4.3.  Examples
 27.1918 +
 27.1919 +      [C] QUIT
 27.1920 +      [S] 205 closing connection
 27.1921 +      [Server closes connection.]
 27.1922 +
 27.1923 +6.  Article Posting and Retrieval
 27.1924 +
 27.1925 +   News-reading clients have available a variety of mechanisms to
 27.1926 +   retrieve articles via NNTP.  The news articles are stored and indexed
 27.1927 +   using three types of keys.  The first type of key is the message-id
 27.1928 +   of an article and is globally unique.  The second type of key is
 27.1929 +   composed of a newsgroup name and an article number within that
 27.1930 +   newsgroup.  On a particular server, there MUST only be one article
 27.1931 +   with a given number within any newsgroup, and an article MUST NOT
 27.1932 +   have two different numbers in the same newsgroup.  An article can be
 27.1933 +   cross-posted to multiple newsgroups, so there may be multiple keys
 27.1934 +   that point to the same article on the same server; these MAY have
 27.1935 +   different numbers in each newsgroup.  However, this type of key is
 27.1936 +   not required to be globally unique, so the same key MAY refer to
 27.1937 +   different articles on different servers.  (Note that the terms
 27.1938 +   "group" and "newsgroup" are equivalent.)
 27.1939 +
 27.1940 +   The final type of key is the arrival timestamp, giving the time that
 27.1941 +   the article arrived at the server.  The server MUST ensure that
 27.1942 +   article numbers are issued in order of arrival timestamp; that is,
 27.1943 +   articles arriving later MUST have higher numbers than those that
 27.1944 +   arrive earlier.  The server SHOULD allocate the next sequential
 27.1945 +   unused number to each new article.
 27.1946 +
 27.1947 +   Article numbers MUST lie between 1 and 2,147,483,647, inclusive.  The
 27.1948 +   client and server MAY use leading zeroes in specifying article
 27.1949 +   numbers but MUST NOT use more than 16 digits.  In some situations,
 27.1950 +   the value zero replaces an article number to show some special
 27.1951 +   situation.
 27.1952 +
 27.1953 +   Note that it is likely that the article number limit of 2,147,483,647
 27.1954 +   will be increased by a future revision or extension to this
 27.1955 +   specification.  While servers MUST NOT send article numbers greater
 27.1956 +   than this current limit, client and server developers are advised to
 27.1957 +
 27.1958 +
 27.1959 +
 27.1960 +Feather                     Standards Track                    [Page 35]
 27.1961 +
 27.1962 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.1963 +
 27.1964 +
 27.1965 +   use internal structures and datatypes capable of handling larger
 27.1966 +   values in anticipation of such a change.
 27.1967 +
 27.1968 +6.1.  Group and Article Selection
 27.1969 +
 27.1970 +   The following commands are used to set the "currently selected
 27.1971 +   newsgroup" and the "current article number", which are used by
 27.1972 +   various commands.  At the start of an NNTP session, both of these
 27.1973 +   values are set to the special value "invalid".
 27.1974 +
 27.1975 +6.1.1.  GROUP
 27.1976 +
 27.1977 +6.1.1.1.  Usage
 27.1978 +
 27.1979 +   Indicating capability: READER
 27.1980 +
 27.1981 +   Syntax
 27.1982 +     GROUP group
 27.1983 +
 27.1984 +   Responses
 27.1985 +     211 number low high group     Group successfully selected
 27.1986 +     411                           No such newsgroup
 27.1987 +
 27.1988 +   Parameters
 27.1989 +     group     Name of newsgroup
 27.1990 +     number    Estimated number of articles in the group
 27.1991 +     low       Reported low water mark
 27.1992 +     high      Reported high water mark
 27.1993 +
 27.1994 +6.1.1.2.  Description
 27.1995 +
 27.1996 +   The GROUP command selects a newsgroup as the currently selected
 27.1997 +   newsgroup and returns summary information about it.
 27.1998 +
 27.1999 +   The required argument is the name of the newsgroup to be selected
 27.2000 +   (e.g., "news.software.nntp").  A list of valid newsgroups may be
 27.2001 +   obtained by using the LIST ACTIVE command (see Section 7.6.3).
 27.2002 +
 27.2003 +   The successful selection response will return the article numbers of
 27.2004 +   the first and last articles in the group at the moment of selection
 27.2005 +   (these numbers are referred to as the "reported low water mark" and
 27.2006 +   the "reported high water mark") and an estimate of the number of
 27.2007 +   articles in the group currently available.
 27.2008 +
 27.2009 +   If the group is not empty, the estimate MUST be at least the actual
 27.2010 +   number of articles available and MUST be no greater than one more
 27.2011 +   than the difference between the reported low and high water marks.
 27.2012 +   (Some implementations will actually count the number of articles
 27.2013 +
 27.2014 +
 27.2015 +
 27.2016 +Feather                     Standards Track                    [Page 36]
 27.2017 +
 27.2018 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2019 +
 27.2020 +
 27.2021 +   currently stored.  Others will just subtract the low water mark from
 27.2022 +   the high water mark and add one to get an estimate.)
 27.2023 +
 27.2024 +   If the group is empty, one of the following three situations will
 27.2025 +   occur.  Clients MUST accept all three cases; servers MUST NOT
 27.2026 +   represent an empty group in any other way.
 27.2027 +
 27.2028 +   o  The high water mark will be one less than the low water mark, and
 27.2029 +      the estimated article count will be zero.  Servers SHOULD use this
 27.2030 +      method to show an empty group.  This is the only time that the
 27.2031 +      high water mark can be less than the low water mark.
 27.2032 +
 27.2033 +   o  All three numbers will be zero.
 27.2034 +
 27.2035 +   o  The high water mark is greater than or equal to the low water
 27.2036 +      mark.  The estimated article count might be zero or non-zero; if
 27.2037 +      it is non-zero, the same requirements apply as for a non-empty
 27.2038 +      group.
 27.2039 +
 27.2040 +   The set of articles in a group may change after the GROUP command is
 27.2041 +   carried out:
 27.2042 +
 27.2043 +   o  Articles may be removed from the group.
 27.2044 +
 27.2045 +   o  Articles may be reinstated in the group with the same article
 27.2046 +      number, but those articles MUST have numbers no less than the
 27.2047 +      reported low water mark (note that this is a reinstatement of the
 27.2048 +      previous article, not a new article reusing the number).
 27.2049 +
 27.2050 +   o  New articles may be added with article numbers greater than the
 27.2051 +      reported high water mark.  (If an article that was the one with
 27.2052 +      the highest number has been removed and the high water mark has
 27.2053 +      been adjusted accordingly, the next new article will not have the
 27.2054 +      number one greater than the reported high water mark.)
 27.2055 +
 27.2056 +   Except when the group is empty and all three numbers are zero,
 27.2057 +   whenever a subsequent GROUP command for the same newsgroup is issued,
 27.2058 +   either by the same client or a different client, the reported low
 27.2059 +   water mark in the response MUST be no less than that in any previous
 27.2060 +   response for that newsgroup in this session, and it SHOULD be no less
 27.2061 +   than that in any previous response for that newsgroup ever sent to
 27.2062 +   any client.  Any failure to meet the latter condition SHOULD be
 27.2063 +   transient only.  The client may make use of the low water mark to
 27.2064 +   remove all remembered information about articles with lower numbers,
 27.2065 +   as these will never recur.  This includes the situation when the high
 27.2066 +   water mark is one less than the low water mark.  No similar
 27.2067 +   assumption can be made about the high water mark, as this can
 27.2068 +
 27.2069 +
 27.2070 +
 27.2071 +
 27.2072 +Feather                     Standards Track                    [Page 37]
 27.2073 +
 27.2074 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2075 +
 27.2076 +
 27.2077 +   decrease if an article is removed and then increase again if it is
 27.2078 +   reinstated or if new articles arrive.
 27.2079 +
 27.2080 +   When a valid group is selected by means of this command, the
 27.2081 +   currently selected newsgroup MUST be set to that group, and the
 27.2082 +   current article number MUST be set to the first article in the group
 27.2083 +   (this applies even if the group is already the currently selected
 27.2084 +   newsgroup).  If an empty newsgroup is selected, the current article
 27.2085 +   number is made invalid.  If an invalid group is specified, the
 27.2086 +   currently selected newsgroup and current article number MUST NOT be
 27.2087 +   changed.
 27.2088 +
 27.2089 +   The GROUP or LISTGROUP command (see Section 6.1.2) MUST be used by a
 27.2090 +   client, and a successful response received, before any other command
 27.2091 +   is used that depends on the value of the currently selected newsgroup
 27.2092 +   or current article number.
 27.2093 +
 27.2094 +   If the group specified is not available on the server, a 411 response
 27.2095 +   MUST be returned.
 27.2096 +
 27.2097 +6.1.1.3.  Examples
 27.2098 +
 27.2099 +   Example for a group known to the server:
 27.2100 +
 27.2101 +      [C] GROUP misc.test
 27.2102 +      [S] 211 1234 3000234 3002322 misc.test
 27.2103 +
 27.2104 +   Example for a group unknown to the server:
 27.2105 +
 27.2106 +      [C] GROUP example.is.sob.bradner.or.barber
 27.2107 +      [S] 411 example.is.sob.bradner.or.barber is unknown
 27.2108 +
 27.2109 +   Example of an empty group using the preferred response:
 27.2110 +
 27.2111 +      [C] GROUP example.currently.empty.newsgroup
 27.2112 +      [S] 211 0 4000 3999 example.currently.empty.newsgroup
 27.2113 +
 27.2114 +   Example of an empty group using an alternative response:
 27.2115 +
 27.2116 +      [C] GROUP example.currently.empty.newsgroup
 27.2117 +      [S] 211 0 0 0 example.currently.empty.newsgroup
 27.2118 +
 27.2119 +   Example of an empty group using a different alternative response:
 27.2120 +
 27.2121 +      [C] GROUP example.currently.empty.newsgroup
 27.2122 +      [S] 211 0 4000 4321 example.currently.empty.newsgroup
 27.2123 +
 27.2124 +
 27.2125 +
 27.2126 +
 27.2127 +
 27.2128 +Feather                     Standards Track                    [Page 38]
 27.2129 +
 27.2130 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2131 +
 27.2132 +
 27.2133 +   Example reselecting the currently selected newsgroup:
 27.2134 +
 27.2135 +      [C] GROUP misc.test
 27.2136 +      [S] 211 1234 234 567 misc.test
 27.2137 +      [C] STAT 444
 27.2138 +      [S] 223 444 <123456@example.net> retrieved
 27.2139 +      [C] GROUP misc.test
 27.2140 +      [S] 211 1234 234 567 misc.test
 27.2141 +      [C] STAT
 27.2142 +      [S] 223 234 <different@example.net> retrieved
 27.2143 +
 27.2144 +6.1.2.  LISTGROUP
 27.2145 +
 27.2146 +6.1.2.1.  Usage
 27.2147 +
 27.2148 +   Indicating capability: READER
 27.2149 +
 27.2150 +   Syntax
 27.2151 +     LISTGROUP [group [range]]
 27.2152 +
 27.2153 +   Responses
 27.2154 +     211 number low high group     Article numbers follow (multi-line)
 27.2155 +     411                           No such newsgroup
 27.2156 +     412                           No newsgroup selected [1]
 27.2157 +
 27.2158 +   Parameters
 27.2159 +     group     Name of newsgroup
 27.2160 +     range     Range of articles to report
 27.2161 +     number    Estimated number of articles in the group
 27.2162 +     low       Reported low water mark
 27.2163 +     high      Reported high water mark
 27.2164 +
 27.2165 +   [1] The 412 response can only occur if no group has been specified.
 27.2166 +
 27.2167 +6.1.2.2.  Description
 27.2168 +
 27.2169 +   The LISTGROUP command selects a newsgroup in the same manner as the
 27.2170 +   GROUP command (see Section 6.1.1) but also provides a list of article
 27.2171 +   numbers in the newsgroup.  If no group is specified, the currently
 27.2172 +   selected newsgroup is used.
 27.2173 +
 27.2174 +   On success, a list of article numbers is returned as a multi-line
 27.2175 +   data block following the 211 response code (the arguments on the
 27.2176 +   initial response line are the same as for the GROUP command).  The
 27.2177 +   list contains one number per line and is in numerical order.  It
 27.2178 +   lists precisely those articles that exist in the group at the moment
 27.2179 +   of selection (therefore, an empty group produces an empty list).  If
 27.2180 +   the optional range argument is specified, only articles within the
 27.2181 +
 27.2182 +
 27.2183 +
 27.2184 +Feather                     Standards Track                    [Page 39]
 27.2185 +
 27.2186 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2187 +
 27.2188 +
 27.2189 +   range are included in the list (therefore, the list MAY be empty even
 27.2190 +   if the group is not).
 27.2191 +
 27.2192 +   The range argument may be any of the following:
 27.2193 +
 27.2194 +   o  An article number.
 27.2195 +
 27.2196 +   o  An article number followed by a dash to indicate all following.
 27.2197 +
 27.2198 +   o  An article number followed by a dash followed by another article
 27.2199 +      number.
 27.2200 +
 27.2201 +   In the last case, if the second number is less than the first number,
 27.2202 +   then the range contains no articles.  Omitting the range is
 27.2203 +   equivalent to the range 1- being specified.
 27.2204 +
 27.2205 +   If the group specified is not available on the server, a 411 response
 27.2206 +   MUST be returned.  If no group is specified and the currently
 27.2207 +   selected newsgroup is invalid, a 412 response MUST be returned.
 27.2208 +
 27.2209 +   Except that the group argument is optional, that a range argument can
 27.2210 +   be specified, and that a multi-line data block follows the 211
 27.2211 +   response code, the LISTGROUP command is identical to the GROUP
 27.2212 +   command.  In particular, when successful, the command sets the
 27.2213 +   current article number to the first article in the group, if any,
 27.2214 +   even if this is not within the range specified by the second
 27.2215 +   argument.
 27.2216 +
 27.2217 +   Note that the range argument is a new feature in this specification
 27.2218 +   and servers that do not support CAPABILITIES (and therefore do not
 27.2219 +   conform to this specification) are unlikely to support it.
 27.2220 +
 27.2221 +6.1.2.3.  Examples
 27.2222 +
 27.2223 +   Example of LISTGROUP being used to select a group:
 27.2224 +
 27.2225 +      [C] LISTGROUP misc.test
 27.2226 +      [S] 211 2000 3000234 3002322 misc.test list follows
 27.2227 +      [S] 3000234
 27.2228 +      [S] 3000237
 27.2229 +      [S] 3000238
 27.2230 +      [S] 3000239
 27.2231 +      [S] 3002322
 27.2232 +      [S] .
 27.2233 +
 27.2234 +
 27.2235 +
 27.2236 +
 27.2237 +
 27.2238 +
 27.2239 +
 27.2240 +Feather                     Standards Track                    [Page 40]
 27.2241 +
 27.2242 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2243 +
 27.2244 +
 27.2245 +   Example of LISTGROUP on an empty group:
 27.2246 +
 27.2247 +      [C] LISTGROUP example.empty.newsgroup
 27.2248 +      [S] 211 0 0 0 example.empty.newsgroup list follows
 27.2249 +      [S] .
 27.2250 +
 27.2251 +   Example of LISTGROUP on a valid, currently selected newsgroup:
 27.2252 +
 27.2253 +      [C] GROUP misc.test
 27.2254 +      [S] 211 2000 3000234 3002322 misc.test
 27.2255 +      [C] LISTGROUP
 27.2256 +      [S] 211 2000 3000234 3002322 misc.test list follows
 27.2257 +      [S] 3000234
 27.2258 +      [S] 3000237
 27.2259 +      [S] 3000238
 27.2260 +      [S] 3000239
 27.2261 +      [S] 3002322
 27.2262 +      [S] .
 27.2263 +
 27.2264 +   Example of LISTGROUP with a range:
 27.2265 +
 27.2266 +      [C] LISTGROUP misc.test 3000238-3000248
 27.2267 +      [S] 211 2000 3000234 3002322 misc.test list follows
 27.2268 +      [S] 3000238
 27.2269 +      [S] 3000239
 27.2270 +      [S] .
 27.2271 +
 27.2272 +   Example of LISTGROUP with an empty range:
 27.2273 +
 27.2274 +      [C] LISTGROUP misc.test 12345678-
 27.2275 +      [S] 211 2000 3000234 3002322 misc.test list follows
 27.2276 +      [S] .
 27.2277 +
 27.2278 +   Example of LISTGROUP with an invalid range:
 27.2279 +
 27.2280 +      [C] LISTGROUP misc.test 9999-111
 27.2281 +      [S] 211 2000 3000234 3002322 misc.test list follows
 27.2282 +      [S] .
 27.2283 +
 27.2284 +
 27.2285 +
 27.2286 +
 27.2287 +
 27.2288 +
 27.2289 +
 27.2290 +
 27.2291 +
 27.2292 +
 27.2293 +
 27.2294 +
 27.2295 +
 27.2296 +Feather                     Standards Track                    [Page 41]
 27.2297 +
 27.2298 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2299 +
 27.2300 +
 27.2301 +6.1.3.  LAST
 27.2302 +
 27.2303 +6.1.3.1.  Usage
 27.2304 +
 27.2305 +   Indicating capability: READER
 27.2306 +
 27.2307 +   Syntax
 27.2308 +     LAST
 27.2309 +
 27.2310 +   Responses
 27.2311 +     223 n message-id    Article found
 27.2312 +     412                 No newsgroup selected
 27.2313 +     420                 Current article number is invalid
 27.2314 +     422                 No previous article in this group
 27.2315 +
 27.2316 +   Parameters
 27.2317 +     n             Article number
 27.2318 +     message-id    Article message-id
 27.2319 +
 27.2320 +6.1.3.2.  Description
 27.2321 +
 27.2322 +   If the currently selected newsgroup is valid, the current article
 27.2323 +   number MUST be set to the previous article in that newsgroup (that
 27.2324 +   is, the highest existing article number less than the current article
 27.2325 +   number).  If successful, a response indicating the new current
 27.2326 +   article number and the message-id of that article MUST be returned.
 27.2327 +   No article text is sent in response to this command.
 27.2328 +
 27.2329 +   There MAY be no previous article in the group, although the current
 27.2330 +   article number is not the reported low water mark.  There MUST NOT be
 27.2331 +   a previous article when the current article number is the reported
 27.2332 +   low water mark.
 27.2333 +
 27.2334 +   Because articles can be removed and added, the results of multiple
 27.2335 +   LAST and NEXT commands MAY not be consistent over the life of a
 27.2336 +   particular NNTP session.
 27.2337 +
 27.2338 +   If the current article number is already the first article of the
 27.2339 +   newsgroup, a 422 response MUST be returned.  If the current article
 27.2340 +   number is invalid, a 420 response MUST be returned.  If the currently
 27.2341 +   selected newsgroup is invalid, a 412 response MUST be returned.  In
 27.2342 +   all three cases, the currently selected newsgroup and current article
 27.2343 +   number MUST NOT be altered.
 27.2344 +
 27.2345 +
 27.2346 +
 27.2347 +
 27.2348 +
 27.2349 +
 27.2350 +
 27.2351 +
 27.2352 +Feather                     Standards Track                    [Page 42]
 27.2353 +
 27.2354 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2355 +
 27.2356 +
 27.2357 +6.1.3.3.  Examples
 27.2358 +
 27.2359 +   Example of a successful article retrieval using LAST:
 27.2360 +
 27.2361 +      [C] GROUP misc.test
 27.2362 +      [S] 211 1234 3000234 3002322 misc.test
 27.2363 +      [C] NEXT
 27.2364 +      [S] 223 3000237 <668929@example.org> retrieved
 27.2365 +      [C] LAST
 27.2366 +      [S] 223 3000234 <45223423@example.com> retrieved
 27.2367 +
 27.2368 +   Example of an attempt to retrieve an article without having selected
 27.2369 +   a group (via the GROUP command) first:
 27.2370 +
 27.2371 +      [Assumes currently selected newsgroup is invalid.]
 27.2372 +      [C] LAST
 27.2373 +      [S] 412 no newsgroup selected
 27.2374 +
 27.2375 +   Example of an attempt to retrieve an article using the LAST command
 27.2376 +   when the current article number is that of the first article in the
 27.2377 +   group:
 27.2378 +
 27.2379 +      [C] GROUP misc.test
 27.2380 +      [S] 211 1234 3000234 3002322 misc.test
 27.2381 +      [C] LAST
 27.2382 +      [S] 422 No previous article to retrieve
 27.2383 +
 27.2384 +   Example of an attempt to retrieve an article using the LAST command
 27.2385 +   when the currently selected newsgroup is empty:
 27.2386 +
 27.2387 +      [C] GROUP example.empty.newsgroup
 27.2388 +      [S] 211 0 0 0 example.empty.newsgroup
 27.2389 +      [C] LAST
 27.2390 +      [S] 420 No current article selected
 27.2391 +
 27.2392 +
 27.2393 +
 27.2394 +
 27.2395 +
 27.2396 +
 27.2397 +
 27.2398 +
 27.2399 +
 27.2400 +
 27.2401 +
 27.2402 +
 27.2403 +
 27.2404 +
 27.2405 +
 27.2406 +
 27.2407 +
 27.2408 +Feather                     Standards Track                    [Page 43]
 27.2409 +
 27.2410 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2411 +
 27.2412 +
 27.2413 +6.1.4.  NEXT
 27.2414 +
 27.2415 +6.1.4.1.  Usage
 27.2416 +
 27.2417 +   Indicating capability: READER
 27.2418 +
 27.2419 +   Syntax
 27.2420 +     NEXT
 27.2421 +
 27.2422 +   Responses
 27.2423 +     223 n message-id    Article found
 27.2424 +     412                 No newsgroup selected
 27.2425 +     420                 Current article number is invalid
 27.2426 +     421                 No next article in this group
 27.2427 +
 27.2428 +   Parameters
 27.2429 +     n             Article number
 27.2430 +     message-id    Article message-id
 27.2431 +
 27.2432 +6.1.4.2.  Description
 27.2433 +
 27.2434 +   If the currently selected newsgroup is valid, the current article
 27.2435 +   number MUST be set to the next article in that newsgroup (that is,
 27.2436 +   the lowest existing article number greater than the current article
 27.2437 +   number).  If successful, a response indicating the new current
 27.2438 +   article number and the message-id of that article MUST be returned.
 27.2439 +   No article text is sent in response to this command.
 27.2440 +
 27.2441 +   If the current article number is already the last article of the
 27.2442 +   newsgroup, a 421 response MUST be returned.  In all other aspects
 27.2443 +   (apart, of course, from the lack of 422 response), this command is
 27.2444 +   identical to the LAST command (Section 6.1.3).
 27.2445 +
 27.2446 +6.1.4.3.  Examples
 27.2447 +
 27.2448 +   Example of a successful article retrieval using NEXT:
 27.2449 +
 27.2450 +      [C] GROUP misc.test
 27.2451 +      [S] 211 1234 3000234 3002322 misc.test
 27.2452 +      [C] NEXT
 27.2453 +      [S] 223 3000237 <668929@example.org> retrieved
 27.2454 +
 27.2455 +
 27.2456 +
 27.2457 +
 27.2458 +
 27.2459 +
 27.2460 +
 27.2461 +
 27.2462 +
 27.2463 +
 27.2464 +Feather                     Standards Track                    [Page 44]
 27.2465 +
 27.2466 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2467 +
 27.2468 +
 27.2469 +   Example of an attempt to retrieve an article without having selected
 27.2470 +   a group (via the GROUP command) first:
 27.2471 +
 27.2472 +      [Assumes currently selected newsgroup is invalid.]
 27.2473 +      [C] NEXT
 27.2474 +      [S] 412 no newsgroup selected
 27.2475 +
 27.2476 +   Example of an attempt to retrieve an article using the NEXT command
 27.2477 +   when the current article number is that of the last article in the
 27.2478 +   group:
 27.2479 +
 27.2480 +      [C] GROUP misc.test
 27.2481 +      [S] 211 1234 3000234 3002322 misc.test
 27.2482 +      [C] STAT 3002322
 27.2483 +      [S] 223 3002322 <411@example.net> retrieved
 27.2484 +      [C] NEXT
 27.2485 +      [S] 421 No next article to retrieve
 27.2486 +
 27.2487 +   Example of an attempt to retrieve an article using the NEXT command
 27.2488 +   when the currently selected newsgroup is empty:
 27.2489 +
 27.2490 +      [C] GROUP example.empty.newsgroup
 27.2491 +      [S] 211 0 0 0 example.empty.newsgroup
 27.2492 +      [C] NEXT
 27.2493 +      [S] 420 No current article selected
 27.2494 +
 27.2495 +6.2.  Retrieval of Articles and Article Sections
 27.2496 +
 27.2497 +   The ARTICLE, BODY, HEAD, and STAT commands are very similar.  They
 27.2498 +   differ only in the parts of the article that are presented to the
 27.2499 +   client and in the successful response code.  The ARTICLE command is
 27.2500 +   described here in full, while the other three commands are described
 27.2501 +   in terms of the differences.  As specified in Section 3.6, an article
 27.2502 +   consists of two parts: the article headers and the article body.
 27.2503 +
 27.2504 +   When responding to one of these commands, the server MUST present the
 27.2505 +   entire article or appropriate part and MUST NOT attempt to alter or
 27.2506 +   translate it in any way.
 27.2507 +
 27.2508 +
 27.2509 +
 27.2510 +
 27.2511 +
 27.2512 +
 27.2513 +
 27.2514 +
 27.2515 +
 27.2516 +
 27.2517 +
 27.2518 +
 27.2519 +
 27.2520 +Feather                     Standards Track                    [Page 45]
 27.2521 +
 27.2522 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2523 +
 27.2524 +
 27.2525 +6.2.1.  ARTICLE
 27.2526 +
 27.2527 +6.2.1.1.  Usage
 27.2528 +
 27.2529 +   Indicating capability: READER
 27.2530 +
 27.2531 +   Syntax
 27.2532 +     ARTICLE message-id
 27.2533 +     ARTICLE number
 27.2534 +     ARTICLE
 27.2535 +
 27.2536 +   Responses
 27.2537 +
 27.2538 +   First form (message-id specified)
 27.2539 +     220 0|n message-id    Article follows (multi-line)
 27.2540 +     430                   No article with that message-id
 27.2541 +
 27.2542 +   Second form (article number specified)
 27.2543 +     220 n message-id      Article follows (multi-line)
 27.2544 +     412                   No newsgroup selected
 27.2545 +     423                   No article with that number
 27.2546 +
 27.2547 +   Third form (current article number used)
 27.2548 +     220 n message-id      Article follows (multi-line)
 27.2549 +     412                   No newsgroup selected
 27.2550 +     420                   Current article number is invalid
 27.2551 +
 27.2552 +   Parameters
 27.2553 +     number        Requested article number
 27.2554 +     n             Returned article number
 27.2555 +     message-id    Article message-id
 27.2556 +
 27.2557 +6.2.1.2.  Description
 27.2558 +
 27.2559 +   The ARTICLE command selects an article according to the arguments and
 27.2560 +   presents the entire article (that is, the headers, an empty line, and
 27.2561 +   the body, in that order) to the client.  The command has three forms.
 27.2562 +
 27.2563 +   In the first form, a message-id is specified, and the server presents
 27.2564 +   the article with that message-id.  In this case, the server MUST NOT
 27.2565 +   alter the currently selected newsgroup or current article number.
 27.2566 +   This is both to facilitate the presentation of articles that may be
 27.2567 +   referenced within another article being read, and because of the
 27.2568 +   semantic difficulties of determining the proper sequence and
 27.2569 +   membership of an article that may have been cross-posted to more than
 27.2570 +   one newsgroup.
 27.2571 +
 27.2572 +
 27.2573 +
 27.2574 +
 27.2575 +
 27.2576 +Feather                     Standards Track                    [Page 46]
 27.2577 +
 27.2578 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2579 +
 27.2580 +
 27.2581 +   In the response, the article number MUST be replaced with zero,
 27.2582 +   unless there is a currently selected newsgroup and the article is
 27.2583 +   present in that group, in which case the server MAY use the article's
 27.2584 +   number in that group.  (The server is not required to determine
 27.2585 +   whether the article is in the currently selected newsgroup or, if so,
 27.2586 +   what article number it has; the client MUST always be prepared for
 27.2587 +   zero to be specified.)  The server MUST NOT provide an article number
 27.2588 +   unless use of that number in a second ARTICLE command immediately
 27.2589 +   following this one would return the same article.  Even if the server
 27.2590 +   chooses to return article numbers in these circumstances, it need not
 27.2591 +   do so consistently; it MAY return zero to any such command (also see
 27.2592 +   the STAT examples, Section 6.2.4.3).
 27.2593 +
 27.2594 +   In the second form, an article number is specified.  If there is an
 27.2595 +   article with that number in the currently selected newsgroup, the
 27.2596 +   server MUST set the current article number to that number.
 27.2597 +
 27.2598 +   In the third form, the article indicated by the current article
 27.2599 +   number in the currently selected newsgroup is used.
 27.2600 +
 27.2601 +   Note that a previously valid article number MAY become invalid if the
 27.2602 +   article has been removed.  A previously invalid article number MAY
 27.2603 +   become valid if the article has been reinstated, but this article
 27.2604 +   number MUST be no less than the reported low water mark for that
 27.2605 +   group.
 27.2606 +
 27.2607 +   The server MUST NOT change the currently selected newsgroup as a
 27.2608 +   result of this command.  The server MUST NOT change the current
 27.2609 +   article number except when an article number argument was provided
 27.2610 +   and the article exists; in particular, it MUST NOT change it
 27.2611 +   following an unsuccessful response.
 27.2612 +
 27.2613 +   Since the message-id is unique for each article, it may be used by a
 27.2614 +   client to skip duplicate displays of articles that have been posted
 27.2615 +   more than once, or to more than one newsgroup.
 27.2616 +
 27.2617 +   The article is returned as a multi-line data block following the 220
 27.2618 +   response code.
 27.2619 +
 27.2620 +   If the argument is a message-id and no such article exists, a 430
 27.2621 +   response MUST be returned.  If the argument is a number or is omitted
 27.2622 +   and the currently selected newsgroup is invalid, a 412 response MUST
 27.2623 +   be returned.  If the argument is a number and that article does not
 27.2624 +   exist in the currently selected newsgroup, a 423 response MUST be
 27.2625 +   returned.  If the argument is omitted and the current article number
 27.2626 +   is invalid, a 420 response MUST be returned.
 27.2627 +
 27.2628 +
 27.2629 +
 27.2630 +
 27.2631 +
 27.2632 +Feather                     Standards Track                    [Page 47]
 27.2633 +
 27.2634 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2635 +
 27.2636 +
 27.2637 +6.2.1.3.  Examples
 27.2638 +
 27.2639 +   Example of a successful retrieval of an article (explicitly not using
 27.2640 +   an article number):
 27.2641 +
 27.2642 +      [C] GROUP misc.test
 27.2643 +      [S] 211 1234 3000234 3002322 misc.test
 27.2644 +      [C] ARTICLE
 27.2645 +      [S] 220 3000234 <45223423@example.com>
 27.2646 +      [S] Path: pathost!demo!whitehouse!not-for-mail
 27.2647 +      [S] From: "Demo User" <nobody@example.net>
 27.2648 +      [S] Newsgroups: misc.test
 27.2649 +      [S] Subject: I am just a test article
 27.2650 +      [S] Date: 6 Oct 1998 04:38:40 -0500
 27.2651 +      [S] Organization: An Example Net, Uncertain, Texas
 27.2652 +      [S] Message-ID: <45223423@example.com>
 27.2653 +      [S]
 27.2654 +      [S] This is just a test article.
 27.2655 +      [S] .
 27.2656 +
 27.2657 +   Example of a successful retrieval of an article by message-id:
 27.2658 +
 27.2659 +      [C] ARTICLE <45223423@example.com>
 27.2660 +      [S] 220 0 <45223423@example.com>
 27.2661 +      [S] Path: pathost!demo!whitehouse!not-for-mail
 27.2662 +      [S] From: "Demo User" <nobody@example.net>
 27.2663 +      [S] Newsgroups: misc.test
 27.2664 +      [S] Subject: I am just a test article
 27.2665 +      [S] Date: 6 Oct 1998 04:38:40 -0500
 27.2666 +      [S] Organization: An Example Net, Uncertain, Texas
 27.2667 +      [S] Message-ID: <45223423@example.com>
 27.2668 +      [S]
 27.2669 +      [S] This is just a test article.
 27.2670 +      [S] .
 27.2671 +
 27.2672 +   Example of an unsuccessful retrieval of an article by message-id:
 27.2673 +
 27.2674 +      [C] ARTICLE <i.am.not.there@example.com>
 27.2675 +      [S] 430 No Such Article Found
 27.2676 +
 27.2677 +   Example of an unsuccessful retrieval of an article by number:
 27.2678 +
 27.2679 +      [C] GROUP misc.test
 27.2680 +      [S] 211 1234 3000234 3002322 news.groups
 27.2681 +      [C] ARTICLE 300256
 27.2682 +      [S] 423 No article with that number
 27.2683 +
 27.2684 +
 27.2685 +
 27.2686 +
 27.2687 +
 27.2688 +Feather                     Standards Track                    [Page 48]
 27.2689 +
 27.2690 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2691 +
 27.2692 +
 27.2693 +   Example of an unsuccessful retrieval of an article by number because
 27.2694 +   no newsgroup was selected first:
 27.2695 +
 27.2696 +      [Assumes currently selected newsgroup is invalid.]
 27.2697 +      [C] ARTICLE 300256
 27.2698 +      [S] 412 No newsgroup selected
 27.2699 +
 27.2700 +   Example of an attempt to retrieve an article when the currently
 27.2701 +   selected newsgroup is empty:
 27.2702 +
 27.2703 +      [C] GROUP example.empty.newsgroup
 27.2704 +      [S] 211 0 0 0 example.empty.newsgroup
 27.2705 +      [C] ARTICLE
 27.2706 +      [S] 420 No current article selected
 27.2707 +
 27.2708 +6.2.2.  HEAD
 27.2709 +
 27.2710 +6.2.2.1.  Usage
 27.2711 +
 27.2712 +   This command is mandatory.
 27.2713 +
 27.2714 +   Syntax
 27.2715 +     HEAD message-id
 27.2716 +     HEAD number
 27.2717 +     HEAD
 27.2718 +
 27.2719 +   Responses
 27.2720 +
 27.2721 +   First form (message-id specified)
 27.2722 +     221 0|n message-id    Headers follow (multi-line)
 27.2723 +     430                   No article with that message-id
 27.2724 +
 27.2725 +   Second form (article number specified)
 27.2726 +     221 n message-id      Headers follow (multi-line)
 27.2727 +     412                   No newsgroup selected
 27.2728 +     423                   No article with that number
 27.2729 +
 27.2730 +   Third form (current article number used)
 27.2731 +     221 n message-id      Headers follow (multi-line)
 27.2732 +     412                   No newsgroup selected
 27.2733 +     420                   Current article number is invalid
 27.2734 +
 27.2735 +   Parameters
 27.2736 +     number        Requested article number
 27.2737 +     n             Returned article number
 27.2738 +     message-id    Article message-id
 27.2739 +
 27.2740 +
 27.2741 +
 27.2742 +
 27.2743 +
 27.2744 +Feather                     Standards Track                    [Page 49]
 27.2745 +
 27.2746 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2747 +
 27.2748 +
 27.2749 +6.2.2.2.  Description
 27.2750 +
 27.2751 +   The HEAD command behaves identically to the ARTICLE command except
 27.2752 +   that, if the article exists, the response code is 221 instead of 220
 27.2753 +   and only the headers are presented (the empty line separating the
 27.2754 +   headers and body MUST NOT be included).
 27.2755 +
 27.2756 +6.2.2.3.  Examples
 27.2757 +
 27.2758 +   Example of a successful retrieval of the headers of an article
 27.2759 +   (explicitly not using an article number):
 27.2760 +
 27.2761 +      [C] GROUP misc.test
 27.2762 +      [S] 211 1234 3000234 3002322 misc.test
 27.2763 +      [C] HEAD
 27.2764 +      [S] 221 3000234 <45223423@example.com>
 27.2765 +      [S] Path: pathost!demo!whitehouse!not-for-mail
 27.2766 +      [S] From: "Demo User" <nobody@example.net>
 27.2767 +      [S] Newsgroups: misc.test
 27.2768 +      [S] Subject: I am just a test article
 27.2769 +      [S] Date: 6 Oct 1998 04:38:40 -0500
 27.2770 +      [S] Organization: An Example Net, Uncertain, Texas
 27.2771 +      [S] Message-ID: <45223423@example.com>
 27.2772 +      [S] .
 27.2773 +
 27.2774 +   Example of a successful retrieval of the headers of an article by
 27.2775 +   message-id:
 27.2776 +
 27.2777 +      [C] HEAD <45223423@example.com>
 27.2778 +      [S] 221 0 <45223423@example.com>
 27.2779 +      [S] Path: pathost!demo!whitehouse!not-for-mail
 27.2780 +      [S] From: "Demo User" <nobody@example.net>
 27.2781 +      [S] Newsgroups: misc.test
 27.2782 +      [S] Subject: I am just a test article
 27.2783 +      [S] Date: 6 Oct 1998 04:38:40 -0500
 27.2784 +      [S] Organization: An Example Net, Uncertain, Texas
 27.2785 +      [S] Message-ID: <45223423@example.com>
 27.2786 +      [S] .
 27.2787 +
 27.2788 +   Example of an unsuccessful retrieval of the headers of an article by
 27.2789 +   message-id:
 27.2790 +
 27.2791 +      [C] HEAD <i.am.not.there@example.com>
 27.2792 +      [S] 430 No Such Article Found
 27.2793 +
 27.2794 +
 27.2795 +
 27.2796 +
 27.2797 +
 27.2798 +
 27.2799 +
 27.2800 +Feather                     Standards Track                    [Page 50]
 27.2801 +
 27.2802 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2803 +
 27.2804 +
 27.2805 +   Example of an unsuccessful retrieval of the headers of an article by
 27.2806 +   number:
 27.2807 +
 27.2808 +      [C] GROUP misc.test
 27.2809 +      [S] 211 1234 3000234 3002322 misc.test
 27.2810 +      [C] HEAD 300256
 27.2811 +      [S] 423 No article with that number
 27.2812 +
 27.2813 +   Example of an unsuccessful retrieval of the headers of an article by
 27.2814 +   number because no newsgroup was selected first:
 27.2815 +
 27.2816 +      [Assumes currently selected newsgroup is invalid.]
 27.2817 +      [C] HEAD 300256
 27.2818 +      [S] 412 No newsgroup selected
 27.2819 +
 27.2820 +   Example of an attempt to retrieve the headers of an article when the
 27.2821 +   currently selected newsgroup is empty:
 27.2822 +
 27.2823 +      [C] GROUP example.empty.newsgroup
 27.2824 +      [S] 211 0 0 0 example.empty.newsgroup
 27.2825 +      [C] HEAD
 27.2826 +      [S] 420 No current article selected
 27.2827 +
 27.2828 +6.2.3.  BODY
 27.2829 +
 27.2830 +6.2.3.1.  Usage
 27.2831 +
 27.2832 +   Indicating capability: READER
 27.2833 +
 27.2834 +   Syntax
 27.2835 +     BODY message-id
 27.2836 +     BODY number
 27.2837 +     BODY
 27.2838 +
 27.2839 +   Responses
 27.2840 +
 27.2841 +   First form (message-id specified)
 27.2842 +     222 0|n message-id    Body follows (multi-line)
 27.2843 +     430                   No article with that message-id
 27.2844 +
 27.2845 +   Second form (article number specified)
 27.2846 +     222 n message-id      Body follows (multi-line)
 27.2847 +     412                   No newsgroup selected
 27.2848 +     423                   No article with that number
 27.2849 +
 27.2850 +
 27.2851 +
 27.2852 +
 27.2853 +
 27.2854 +
 27.2855 +
 27.2856 +Feather                     Standards Track                    [Page 51]
 27.2857 +
 27.2858 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2859 +
 27.2860 +
 27.2861 +   Third form (current article number used)
 27.2862 +     222 n message-id      Body follows (multi-line)
 27.2863 +     412                   No newsgroup selected
 27.2864 +     420                   Current article number is invalid
 27.2865 +
 27.2866 +   Parameters
 27.2867 +     number        Requested article number
 27.2868 +     n             Returned article number
 27.2869 +     message-id    Article message-id
 27.2870 +
 27.2871 +6.2.3.2.  Description
 27.2872 +
 27.2873 +   The BODY command behaves identically to the ARTICLE command except
 27.2874 +   that, if the article exists, the response code is 222 instead of 220
 27.2875 +   and only the body is presented (the empty line separating the headers
 27.2876 +   and body MUST NOT be included).
 27.2877 +
 27.2878 +6.2.3.3.  Examples
 27.2879 +
 27.2880 +   Example of a successful retrieval of the body of an article
 27.2881 +   (explicitly not using an article number):
 27.2882 +
 27.2883 +      [C] GROUP misc.test
 27.2884 +      [S] 211 1234 3000234 3002322 misc.test
 27.2885 +      [C] BODY
 27.2886 +      [S] 222 3000234 <45223423@example.com>
 27.2887 +      [S] This is just a test article.
 27.2888 +      [S] .
 27.2889 +
 27.2890 +   Example of a successful retrieval of the body of an article by
 27.2891 +   message-id:
 27.2892 +
 27.2893 +      [C] BODY <45223423@example.com>
 27.2894 +      [S] 222 0 <45223423@example.com>
 27.2895 +      [S] This is just a test article.
 27.2896 +      [S] .
 27.2897 +
 27.2898 +   Example of an unsuccessful retrieval of the body of an article by
 27.2899 +   message-id:
 27.2900 +
 27.2901 +      [C] BODY <i.am.not.there@example.com>
 27.2902 +      [S] 430 No Such Article Found
 27.2903 +
 27.2904 +
 27.2905 +
 27.2906 +
 27.2907 +
 27.2908 +
 27.2909 +
 27.2910 +
 27.2911 +
 27.2912 +Feather                     Standards Track                    [Page 52]
 27.2913 +
 27.2914 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2915 +
 27.2916 +
 27.2917 +   Example of an unsuccessful retrieval of the body of an article by
 27.2918 +   number:
 27.2919 +
 27.2920 +      [C] GROUP misc.test
 27.2921 +      [S] 211 1234 3000234 3002322 misc.test
 27.2922 +      [C] BODY 300256
 27.2923 +      [S] 423 No article with that number
 27.2924 +
 27.2925 +   Example of an unsuccessful retrieval of the body of an article by
 27.2926 +   number because no newsgroup was selected first:
 27.2927 +
 27.2928 +      [Assumes currently selected newsgroup is invalid.]
 27.2929 +      [C] BODY 300256
 27.2930 +      [S] 412 No newsgroup selected
 27.2931 +
 27.2932 +   Example of an attempt to retrieve the body of an article when the
 27.2933 +   currently selected newsgroup is empty:
 27.2934 +
 27.2935 +      [C] GROUP example.empty.newsgroup
 27.2936 +      [S] 211 0 0 0 example.empty.newsgroup
 27.2937 +      [C] BODY
 27.2938 +      [S] 420 No current article selected
 27.2939 +
 27.2940 +6.2.4.  STAT
 27.2941 +
 27.2942 +6.2.4.1.  Usage
 27.2943 +
 27.2944 +   This command is mandatory.
 27.2945 +
 27.2946 +   Syntax
 27.2947 +     STAT message-id
 27.2948 +     STAT number
 27.2949 +     STAT
 27.2950 +
 27.2951 +   Responses
 27.2952 +
 27.2953 +   First form (message-id specified)
 27.2954 +     223 0|n message-id    Article exists
 27.2955 +     430                   No article with that message-id
 27.2956 +
 27.2957 +   Second form (article number specified)
 27.2958 +     223 n message-id      Article exists
 27.2959 +     412                   No newsgroup selected
 27.2960 +     423                   No article with that number
 27.2961 +
 27.2962 +
 27.2963 +
 27.2964 +
 27.2965 +
 27.2966 +
 27.2967 +
 27.2968 +Feather                     Standards Track                    [Page 53]
 27.2969 +
 27.2970 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.2971 +
 27.2972 +
 27.2973 +   Third form (current article number used)
 27.2974 +     223 n message-id      Article exists
 27.2975 +     412                   No newsgroup selected
 27.2976 +     420                   Current article number is invalid
 27.2977 +
 27.2978 +   Parameters
 27.2979 +     number        Requested article number
 27.2980 +     n             Returned article number
 27.2981 +     message-id    Article message-id
 27.2982 +
 27.2983 +6.2.4.2.  Description
 27.2984 +
 27.2985 +   The STAT command behaves identically to the ARTICLE command except
 27.2986 +   that, if the article exists, it is NOT presented to the client and
 27.2987 +   the response code is 223 instead of 220.  Note that the response is
 27.2988 +   NOT multi-line.
 27.2989 +
 27.2990 +   This command allows the client to determine whether an article exists
 27.2991 +   and, in the second and third forms, what its message-id is, without
 27.2992 +   having to process an arbitrary amount of text.
 27.2993 +
 27.2994 +6.2.4.3.  Examples
 27.2995 +
 27.2996 +   Example of STAT on an existing article (explicitly not using an
 27.2997 +   article number):
 27.2998 +
 27.2999 +      [C] GROUP misc.test
 27.3000 +      [S] 211 1234 3000234 3002322 misc.test
 27.3001 +      [C] STAT
 27.3002 +      [S] 223 3000234 <45223423@example.com>
 27.3003 +
 27.3004 +   Example of STAT on an existing article by message-id:
 27.3005 +
 27.3006 +      [C] STAT <45223423@example.com>
 27.3007 +      [S] 223 0 <45223423@example.com>
 27.3008 +
 27.3009 +   Example of STAT on an article not on the server by message-id:
 27.3010 +
 27.3011 +      [C] STAT <i.am.not.there@example.com>
 27.3012 +      [S] 430 No Such Article Found
 27.3013 +
 27.3014 +   Example of STAT on an article not in the server by number:
 27.3015 +
 27.3016 +      [C] GROUP misc.test
 27.3017 +      [S] 211 1234 3000234 3002322 misc.test
 27.3018 +      [C] STAT 300256
 27.3019 +      [S] 423 No article with that number
 27.3020 +
 27.3021 +
 27.3022 +
 27.3023 +
 27.3024 +Feather                     Standards Track                    [Page 54]
 27.3025 +
 27.3026 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3027 +
 27.3028 +
 27.3029 +   Example of STAT on an article by number when no newsgroup was
 27.3030 +   selected first:
 27.3031 +
 27.3032 +      [Assumes currently selected newsgroup is invalid.]
 27.3033 +      [C] STAT 300256
 27.3034 +      [S] 412 No newsgroup selected
 27.3035 +
 27.3036 +   Example of STAT on an article when the currently selected newsgroup
 27.3037 +   is empty:
 27.3038 +
 27.3039 +      [C] GROUP example.empty.newsgroup
 27.3040 +      [S] 211 0 0 0 example.empty.newsgroup
 27.3041 +      [C] STAT
 27.3042 +      [S] 420 No current article selected
 27.3043 +
 27.3044 +   Example of STAT by message-id on a server that sometimes reports the
 27.3045 +   actual article number:
 27.3046 +
 27.3047 +      [C] GROUP misc.test
 27.3048 +      [S] 211 1234 3000234 3002322 misc.test
 27.3049 +      [C] STAT
 27.3050 +      [S] 223 3000234 <45223423@example.com>
 27.3051 +      [C] STAT <45223423@example.com>
 27.3052 +      [S] 223 0 <45223423@example.com>
 27.3053 +      [C] STAT <45223423@example.com>
 27.3054 +      [S] 223 3000234 <45223423@example.com>
 27.3055 +      [C] GROUP example.empty.newsgroup
 27.3056 +      [S] 211 0 0 0 example.empty.newsgroup
 27.3057 +      [C] STAT <45223423@example.com>
 27.3058 +      [S] 223 0 <45223423@example.com>
 27.3059 +      [C] GROUP alt.crossposts
 27.3060 +      [S] 211 9999 111111 222222 alt.crossposts
 27.3061 +      [C] STAT <45223423@example.com>
 27.3062 +      [S] 223 123456 <45223423@example.com>
 27.3063 +      [C] STAT
 27.3064 +      [S] 223 111111 <23894720@example.com>
 27.3065 +
 27.3066 +   The first STAT command establishes the identity of an article in the
 27.3067 +   group.  The second and third show that the server may, but need not,
 27.3068 +   give the article number when the message-id is specified.  The fourth
 27.3069 +   STAT command shows that zero must be specified if the article isn't
 27.3070 +   in the currently selected newsgroup.  The fifth shows that the
 27.3071 +   number, if provided, must be that relating to the currently selected
 27.3072 +   newsgroup.  The last one shows that the current article number is
 27.3073 +   still not changed by the use of STAT with a message-id even if it
 27.3074 +   returns an article number.
 27.3075 +
 27.3076 +
 27.3077 +
 27.3078 +
 27.3079 +
 27.3080 +Feather                     Standards Track                    [Page 55]
 27.3081 +
 27.3082 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3083 +
 27.3084 +
 27.3085 +6.3.  Article Posting
 27.3086 +
 27.3087 +   Article posting is done in one of two ways: individual article
 27.3088 +   posting from news-reading clients using POST, and article transfer
 27.3089 +   from other news servers using IHAVE.
 27.3090 +
 27.3091 +6.3.1.  POST
 27.3092 +
 27.3093 +6.3.1.1.  Usage
 27.3094 +
 27.3095 +   Indicating capability: POST
 27.3096 +
 27.3097 +   This command MUST NOT be pipelined.
 27.3098 +
 27.3099 +   Syntax
 27.3100 +     POST
 27.3101 +
 27.3102 +   Responses
 27.3103 +
 27.3104 +   Initial responses
 27.3105 +     340    Send article to be posted
 27.3106 +     440    Posting not permitted
 27.3107 +
 27.3108 +   Subsequent responses
 27.3109 +     240    Article received OK
 27.3110 +     441    Posting failed
 27.3111 +
 27.3112 +6.3.1.2.  Description
 27.3113 +
 27.3114 +   If posting is allowed, a 340 response MUST be returned to indicate
 27.3115 +   that the article to be posted should be sent.  If posting is
 27.3116 +   prohibited for some installation-dependent reason, a 440 response
 27.3117 +   MUST be returned.
 27.3118 +
 27.3119 +   If posting is permitted, the article MUST be in the format specified
 27.3120 +   in Section 3.6 and MUST be sent by the client to the server as a
 27.3121 +   multi-line data block (see Section 3.1.1).  Thus a single dot (".")
 27.3122 +   on a line indicates the end of the text, and lines starting with a
 27.3123 +   dot in the original text have that dot doubled during transmission.
 27.3124 +
 27.3125 +   Following the presentation of the termination sequence by the client,
 27.3126 +   the server MUST return a response indicating success or failure of
 27.3127 +   the article transfer.  Note that response codes 340 and 440 are used
 27.3128 +   in direct response to the POST command while 240 and 441 are returned
 27.3129 +   after the article is sent.
 27.3130 +
 27.3131 +
 27.3132 +
 27.3133 +
 27.3134 +
 27.3135 +
 27.3136 +Feather                     Standards Track                    [Page 56]
 27.3137 +
 27.3138 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3139 +
 27.3140 +
 27.3141 +   A response of 240 SHOULD indicate that, barring unforeseen server
 27.3142 +   errors, the posted article will be made available on the server
 27.3143 +   and/or transferred to other servers, as appropriate, possibly
 27.3144 +   following further processing.  In other words, articles not wanted by
 27.3145 +   the server SHOULD be rejected with a 441 response, rather than being
 27.3146 +   accepted and then discarded silently.  However, the client SHOULD NOT
 27.3147 +   assume that the article has been successfully transferred unless it
 27.3148 +   receives an affirmative response from the server and SHOULD NOT
 27.3149 +   assume that it is being made available to other clients without
 27.3150 +   explicitly checking (for example, using the STAT command).
 27.3151 +
 27.3152 +   If the session is interrupted before the response is received, it is
 27.3153 +   possible that an affirmative response was sent but has been lost.
 27.3154 +   Therefore, in any subsequent session, the client SHOULD either check
 27.3155 +   whether the article was successfully posted before resending or
 27.3156 +   ensure that the server will allocate the same message-id to the new
 27.3157 +   attempt (see Appendix A.2).  The latter approach is preferred since
 27.3158 +   the article might not have been made available for reading yet (for
 27.3159 +   example, it may have to go through a moderation process).
 27.3160 +
 27.3161 +6.3.1.3.  Examples
 27.3162 +
 27.3163 +   Example of a successful posting:
 27.3164 +
 27.3165 +      [C] POST
 27.3166 +      [S] 340 Input article; end with <CR-LF>.<CR-LF>
 27.3167 +      [C] From: "Demo User" <nobody@example.net>
 27.3168 +      [C] Newsgroups: misc.test
 27.3169 +      [C] Subject: I am just a test article
 27.3170 +      [C] Organization: An Example Net
 27.3171 +      [C]
 27.3172 +      [C] This is just a test article.
 27.3173 +      [C] .
 27.3174 +      [S] 240 Article received OK
 27.3175 +
 27.3176 +   Example of an unsuccessful posting:
 27.3177 +
 27.3178 +      [C] POST
 27.3179 +      [S] 340 Input article; end with <CR-LF>.<CR-LF>
 27.3180 +      [C] From: "Demo User" <nobody@example.net>
 27.3181 +      [C] Newsgroups: misc.test
 27.3182 +      [C] Subject: I am just a test article
 27.3183 +      [C] Organization: An Example Net
 27.3184 +      [C]
 27.3185 +      [C] This is just a test article.
 27.3186 +      [C] .
 27.3187 +      [S] 441 Posting failed
 27.3188 +
 27.3189 +
 27.3190 +
 27.3191 +
 27.3192 +Feather                     Standards Track                    [Page 57]
 27.3193 +
 27.3194 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3195 +
 27.3196 +
 27.3197 +   Example of an attempt to post when posting is not allowed:
 27.3198 +
 27.3199 +      [Initial connection set-up completed.]
 27.3200 +      [S] 201 NNTP Service Ready, posting prohibited
 27.3201 +      [C] POST
 27.3202 +      [S] 440 Posting not permitted
 27.3203 +
 27.3204 +6.3.2.  IHAVE
 27.3205 +
 27.3206 +6.3.2.1.  Usage
 27.3207 +
 27.3208 +   Indicating capability: IHAVE
 27.3209 +
 27.3210 +   This command MUST NOT be pipelined.
 27.3211 +
 27.3212 +   Syntax
 27.3213 +     IHAVE message-id
 27.3214 +
 27.3215 +   Responses
 27.3216 +
 27.3217 +   Initial responses
 27.3218 +     335    Send article to be transferred
 27.3219 +     435    Article not wanted
 27.3220 +     436    Transfer not possible; try again later
 27.3221 +
 27.3222 +   Subsequent responses
 27.3223 +     235    Article transferred OK
 27.3224 +     436    Transfer failed; try again later
 27.3225 +     437    Transfer rejected; do not retry
 27.3226 +
 27.3227 +   Parameters
 27.3228 +     message-id    Article message-id
 27.3229 +
 27.3230 +6.3.2.2.  Description
 27.3231 +
 27.3232 +   The IHAVE command informs the server that the client has an article
 27.3233 +   with the specified message-id.  If the server desires a copy of that
 27.3234 +   article, a 335 response MUST be returned, instructing the client to
 27.3235 +   send the entire article.  If the server does not want the article
 27.3236 +   (if, for example, the server already has a copy of it), a 435
 27.3237 +   response MUST be returned, indicating that the article is not wanted.
 27.3238 +   Finally, if the article isn't wanted immediately but the client
 27.3239 +   should retry later if possible (if, for example, another client is in
 27.3240 +   the process of sending the same article to the server), a 436
 27.3241 +   response MUST be returned.
 27.3242 +
 27.3243 +
 27.3244 +
 27.3245 +
 27.3246 +
 27.3247 +
 27.3248 +Feather                     Standards Track                    [Page 58]
 27.3249 +
 27.3250 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3251 +
 27.3252 +
 27.3253 +   If transmission of the article is requested, the client MUST send the
 27.3254 +   entire article, including headers and body, to the server as a
 27.3255 +   multi-line data block (see Section 3.1.1).  Thus, a single dot (".")
 27.3256 +   on a line indicates the end of the text, and lines starting with a
 27.3257 +   dot in the original text have that dot doubled during transmission.
 27.3258 +   The server MUST return a 235 response, indicating that the article
 27.3259 +   was successfully transferred; a 436 response, indicating that the
 27.3260 +   transfer failed but should be tried again later; or a 437 response,
 27.3261 +   indicating that the article was rejected.
 27.3262 +
 27.3263 +   This function differs from the POST command in that it is intended
 27.3264 +   for use in transferring already-posted articles between hosts.  It
 27.3265 +   SHOULD NOT be used when the client is a personal news-reading
 27.3266 +   program, since use of this command indicates that the article has
 27.3267 +   already been posted at another site and is simply being forwarded
 27.3268 +   from another host.  However, despite this, the server MAY elect not
 27.3269 +   to post or forward the article if, after further examination of the
 27.3270 +   article, it deems it inappropriate to do so.  Reasons for such
 27.3271 +   subsequent rejection of an article may include problems such as
 27.3272 +   inappropriate newsgroups or distributions, disc space limitations,
 27.3273 +   article lengths, garbled headers, and the like.  These are typically
 27.3274 +   restrictions enforced by the server host's news software and not
 27.3275 +   necessarily by the NNTP server itself.
 27.3276 +
 27.3277 +   The client SHOULD NOT assume that the article has been successfully
 27.3278 +   transferred unless it receives an affirmative response from the
 27.3279 +   server.  A lack of response (such as a dropped network connection or
 27.3280 +   a network timeout) SHOULD be treated the same as a 436 response.
 27.3281 +
 27.3282 +   Because some news server software may not immediately be able to
 27.3283 +   determine whether an article is suitable for posting or forwarding,
 27.3284 +   an NNTP server MAY acknowledge the successful transfer of the article
 27.3285 +   (with a 235 response) but later silently discard it.
 27.3286 +
 27.3287 +
 27.3288 +
 27.3289 +
 27.3290 +
 27.3291 +
 27.3292 +
 27.3293 +
 27.3294 +
 27.3295 +
 27.3296 +
 27.3297 +
 27.3298 +
 27.3299 +
 27.3300 +
 27.3301 +
 27.3302 +
 27.3303 +
 27.3304 +Feather                     Standards Track                    [Page 59]
 27.3305 +
 27.3306 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3307 +
 27.3308 +
 27.3309 +6.3.2.3.  Examples
 27.3310 +
 27.3311 +   Example of successfully sending an article to another site:
 27.3312 +
 27.3313 +      [C] IHAVE <i.am.an.article.you.will.want@example.com>
 27.3314 +      [S] 335 Send it; end with <CR-LF>.<CR-LF>
 27.3315 +      [C] Path: pathost!demo!somewhere!not-for-mail
 27.3316 +      [C] From: "Demo User" <nobody@example.com>
 27.3317 +      [C] Newsgroups: misc.test
 27.3318 +      [C] Subject: I am just a test article
 27.3319 +      [C] Date: 6 Oct 1998 04:38:40 -0500
 27.3320 +      [C] Organization: An Example Com, San Jose, CA
 27.3321 +      [C] Message-ID: <i.am.an.article.you.will.want@example.com>
 27.3322 +      [C]
 27.3323 +      [C] This is just a test article.
 27.3324 +      [C] .
 27.3325 +      [S] 235 Article transferred OK
 27.3326 +
 27.3327 +   Example of sending an article to another site that rejects it.  Note
 27.3328 +   that the message-id in the IHAVE command is not the same as the one
 27.3329 +   in the article headers; while this is bad practice and SHOULD NOT be
 27.3330 +   done, it is not forbidden.
 27.3331 +
 27.3332 +      [C] IHAVE <i.am.an.article.you.will.want@example.com>
 27.3333 +      [S] 335 Send it; end with <CR-LF>.<CR-LF>
 27.3334 +      [C] Path: pathost!demo!somewhere!not-for-mail
 27.3335 +      [C] From: "Demo User" <nobody@example.com>
 27.3336 +      [C] Newsgroups: misc.test
 27.3337 +      [C] Subject: I am just a test article
 27.3338 +      [C] Date: 6 Oct 1998 04:38:40 -0500
 27.3339 +      [C] Organization: An Example Com, San Jose, CA
 27.3340 +      [C] Message-ID: <i.am.an.article.you.have@example.com>
 27.3341 +      [C]
 27.3342 +      [C] This is just a test article.
 27.3343 +      [C] .
 27.3344 +      [S] 437 Article rejected; don't send again
 27.3345 +
 27.3346 +
 27.3347 +
 27.3348 +
 27.3349 +
 27.3350 +
 27.3351 +
 27.3352 +
 27.3353 +
 27.3354 +
 27.3355 +
 27.3356 +
 27.3357 +
 27.3358 +
 27.3359 +
 27.3360 +Feather                     Standards Track                    [Page 60]
 27.3361 +
 27.3362 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3363 +
 27.3364 +
 27.3365 +   Example of sending an article to another site where the transfer
 27.3366 +   fails:
 27.3367 +
 27.3368 +      [C] IHAVE <i.am.an.article.you.will.want@example.com>
 27.3369 +      [S] 335 Send it; end with <CR-LF>.<CR-LF>
 27.3370 +      [C] Path: pathost!demo!somewhere!not-for-mail
 27.3371 +      [C] From: "Demo User" <nobody@example.com>
 27.3372 +      [C] Newsgroups: misc.test
 27.3373 +      [C] Subject: I am just a test article
 27.3374 +      [C] Date: 6 Oct 1998 04:38:40 -0500
 27.3375 +      [C] Organization: An Example Com, San Jose, CA
 27.3376 +      [C] Message-ID: <i.am.an.article.you.will.want@example.com>
 27.3377 +      [C]
 27.3378 +      [C] This is just a test article.
 27.3379 +      [C] .
 27.3380 +      [S] 436 Transfer failed
 27.3381 +
 27.3382 +   Example of sending an article to a site that already has it:
 27.3383 +
 27.3384 +      [C] IHAVE <i.am.an.article.you.have@example.com>
 27.3385 +      [S] 435 Duplicate
 27.3386 +
 27.3387 +   Example of sending an article to a site that requests that the
 27.3388 +   article be tried again later:
 27.3389 +
 27.3390 +      [C] IHAVE <i.am.an.article.you.defer@example.com>
 27.3391 +      [S] 436 Retry later
 27.3392 +
 27.3393 +7.  Information Commands
 27.3394 +
 27.3395 +   This section lists other commands that may be used at any time
 27.3396 +   between the beginning of a session and its termination.  Using these
 27.3397 +   commands does not alter any state information, but the response
 27.3398 +   generated from their use may provide useful information to clients.
 27.3399 +
 27.3400 +7.1.  DATE
 27.3401 +
 27.3402 +7.1.1.  Usage
 27.3403 +
 27.3404 +   Indicating capability: READER
 27.3405 +
 27.3406 +   Syntax
 27.3407 +     DATE
 27.3408 +
 27.3409 +   Responses
 27.3410 +     111 yyyymmddhhmmss    Server date and time
 27.3411 +
 27.3412 +
 27.3413 +
 27.3414 +
 27.3415 +
 27.3416 +Feather                     Standards Track                    [Page 61]
 27.3417 +
 27.3418 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3419 +
 27.3420 +
 27.3421 +   Parameters
 27.3422 +     yyyymmddhhmmss    Current UTC date and time on server
 27.3423 +
 27.3424 +7.1.2.  Description
 27.3425 +
 27.3426 +   This command exists to help clients find out the current Coordinated
 27.3427 +   Universal Time [TF.686-1] from the server's perspective.  This
 27.3428 +   command SHOULD NOT be used as a substitute for NTP [RFC1305] but to
 27.3429 +   provide information that might be useful when using the NEWNEWS
 27.3430 +   command (see Section 7.4).
 27.3431 +
 27.3432 +   The DATE command MUST return a timestamp from the same clock as is
 27.3433 +   used for determining article arrival and group creation times (see
 27.3434 +   Section 6).  This clock SHOULD be monotonic, and adjustments SHOULD
 27.3435 +   be made by running it fast or slow compared to "real" time rather
 27.3436 +   than by making sudden jumps.  A system providing NNTP service SHOULD
 27.3437 +   keep the system clock as accurate as possible, either with NTP or by
 27.3438 +   some other method.
 27.3439 +
 27.3440 +   The server MUST return a 111 response specifying the date and time on
 27.3441 +   the server in the form yyyymmddhhmmss.  This date and time is in
 27.3442 +   Coordinated Universal Time.
 27.3443 +
 27.3444 +7.1.3.  Examples
 27.3445 +
 27.3446 +      [C] DATE
 27.3447 +      [S] 111 19990623135624
 27.3448 +
 27.3449 +7.2.  HELP
 27.3450 +
 27.3451 +7.2.1.  Usage
 27.3452 +
 27.3453 +   This command is mandatory.
 27.3454 +
 27.3455 +   Syntax
 27.3456 +     HELP
 27.3457 +
 27.3458 +   Responses
 27.3459 +     100    Help text follows (multi-line)
 27.3460 +
 27.3461 +7.2.2.  Description
 27.3462 +
 27.3463 +   This command provides a short summary of the commands that are
 27.3464 +   understood by this implementation of the server.  The help text will
 27.3465 +   be presented as a multi-line data block following the 100 response
 27.3466 +   code.
 27.3467 +
 27.3468 +
 27.3469 +
 27.3470 +
 27.3471 +
 27.3472 +Feather                     Standards Track                    [Page 62]
 27.3473 +
 27.3474 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3475 +
 27.3476 +
 27.3477 +   This text is not guaranteed to be in any particular format (but must
 27.3478 +   be UTF-8) and MUST NOT be used by clients as a replacement for the
 27.3479 +   CAPABILITIES command described in Section 5.2.
 27.3480 +
 27.3481 +7.2.3.  Examples
 27.3482 +
 27.3483 +      [C] HELP
 27.3484 +      [S] 100 Help text follows
 27.3485 +      [S] This is some help text.  There is no specific
 27.3486 +      [S] formatting requirement for this test, though
 27.3487 +      [S] it is customary for it to list the valid commands
 27.3488 +      [S] and give a brief definition of what they do.
 27.3489 +      [S] .
 27.3490 +
 27.3491 +7.3.  NEWGROUPS
 27.3492 +
 27.3493 +7.3.1.  Usage
 27.3494 +
 27.3495 +   Indicating capability: READER
 27.3496 +
 27.3497 +   Syntax
 27.3498 +     NEWGROUPS date time [GMT]
 27.3499 +
 27.3500 +   Responses
 27.3501 +     231    List of new newsgroups follows (multi-line)
 27.3502 +
 27.3503 +   Parameters
 27.3504 +     date    Date in yymmdd or yyyymmdd format
 27.3505 +     time    Time in hhmmss format
 27.3506 +
 27.3507 +7.3.2.  Description
 27.3508 +
 27.3509 +   This command returns a list of newsgroups created on the server since
 27.3510 +   the specified date and time.  The results are in the same format as
 27.3511 +   the LIST ACTIVE command (see Section 7.6.3).  However, they MAY
 27.3512 +   include groups not available on the server (and so not returned by
 27.3513 +   LIST ACTIVE) and MAY omit groups for which the creation date is not
 27.3514 +   available.
 27.3515 +
 27.3516 +   The date is specified as 6 or 8 digits in the format [xx]yymmdd,
 27.3517 +   where xx is the first two digits of the year (19-99), yy is the last
 27.3518 +   two digits of the year (00-99), mm is the month (01-12), and dd is
 27.3519 +   the day of the month (01-31).  Clients SHOULD specify all four digits
 27.3520 +   of the year.  If the first two digits of the year are not specified
 27.3521 +   (this is supported only for backward compatibility), the year is to
 27.3522 +   be taken from the current century if yy is smaller than or equal to
 27.3523 +   the current year, and the previous century otherwise.
 27.3524 +
 27.3525 +
 27.3526 +
 27.3527 +
 27.3528 +Feather                     Standards Track                    [Page 63]
 27.3529 +
 27.3530 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3531 +
 27.3532 +
 27.3533 +   The time is specified as 6 digits in the format hhmmss, where hh is
 27.3534 +   the hours in the 24-hour clock (00-23), mm is the minutes (00-59),
 27.3535 +   and ss is the seconds (00-60, to allow for leap seconds).  The token
 27.3536 +   "GMT" specifies that the date and time are given in Coordinated
 27.3537 +   Universal Time [TF.686-1]; if it is omitted, then the date and time
 27.3538 +   are specified in the server's local timezone.  Note that there is no
 27.3539 +   way of using the protocol specified in this document to establish the
 27.3540 +   server's local timezone.
 27.3541 +
 27.3542 +   Note that an empty list is a possible valid response and indicates
 27.3543 +   that there are no new newsgroups since that date-time.
 27.3544 +
 27.3545 +   Clients SHOULD make all queries using Coordinated Universal Time
 27.3546 +   (i.e., by including the "GMT" argument) when possible.
 27.3547 +
 27.3548 +7.3.3.  Examples
 27.3549 +
 27.3550 +   Example where there are new groups:
 27.3551 +
 27.3552 +      [C] NEWGROUPS 19990624 000000 GMT
 27.3553 +      [S] 231 list of new newsgroups follows
 27.3554 +      [S] alt.rfc-writers.recovery 4 1 y
 27.3555 +      [S] tx.natives.recovery 89 56 y
 27.3556 +      [S] .
 27.3557 +
 27.3558 +   Example where there are no new groups:
 27.3559 +
 27.3560 +      [C] NEWGROUPS 19990624 000000 GMT
 27.3561 +      [S] 231 list of new newsgroups follows
 27.3562 +      [S] .
 27.3563 +
 27.3564 +7.4.  NEWNEWS
 27.3565 +
 27.3566 +7.4.1.  Usage
 27.3567 +
 27.3568 +   Indicating capability: NEWNEWS
 27.3569 +
 27.3570 +   Syntax
 27.3571 +     NEWNEWS wildmat date time [GMT]
 27.3572 +
 27.3573 +   Responses
 27.3574 +     230    List of new articles follows (multi-line)
 27.3575 +
 27.3576 +   Parameters
 27.3577 +     wildmat    Newsgroups of interest
 27.3578 +     date       Date in yymmdd or yyyymmdd format
 27.3579 +     time       Time in hhmmss format
 27.3580 +
 27.3581 +
 27.3582 +
 27.3583 +
 27.3584 +Feather                     Standards Track                    [Page 64]
 27.3585 +
 27.3586 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3587 +
 27.3588 +
 27.3589 +7.4.2.  Description
 27.3590 +
 27.3591 +   This command returns a list of message-ids of articles posted or
 27.3592 +   received on the server, in the newsgroups whose names match the
 27.3593 +   wildmat, since the specified date and time.  One message-id is sent
 27.3594 +   on each line; the order of the response has no specific significance
 27.3595 +   and may vary from response to response in the same session.  A
 27.3596 +   message-id MAY appear more than once; if it does, it has the same
 27.3597 +   meaning as if it appeared only once.
 27.3598 +
 27.3599 +   Date and time are in the same format as the NEWGROUPS command (see
 27.3600 +   Section 7.3).
 27.3601 +
 27.3602 +   Note that an empty list is a possible valid response and indicates
 27.3603 +   that there is currently no new news in the relevant groups.
 27.3604 +
 27.3605 +   Clients SHOULD make all queries in Coordinated Universal Time (i.e.,
 27.3606 +   by using the "GMT" argument) when possible.
 27.3607 +
 27.3608 +7.4.3.  Examples
 27.3609 +
 27.3610 +   Example where there are new articles:
 27.3611 +
 27.3612 +      [C] NEWNEWS news.*,sci.* 19990624 000000 GMT
 27.3613 +      [S] 230 list of new articles by message-id follows
 27.3614 +      [S] <i.am.a.new.article@example.com>
 27.3615 +      [S] <i.am.another.new.article@example.com>
 27.3616 +      [S] .
 27.3617 +
 27.3618 +   Example where there are no new articles:
 27.3619 +
 27.3620 +      [C] NEWNEWS alt.* 19990624 000000 GMT
 27.3621 +      [S] 230 list of new articles by message-id follows
 27.3622 +      [S] .
 27.3623 +
 27.3624 +7.5.  Time
 27.3625 +
 27.3626 +   As described in Section 6, each article has an arrival timestamp.
 27.3627 +   Each newsgroup also has a creation timestamp.  These timestamps are
 27.3628 +   used by the NEWNEWS and NEWGROUP commands to construct their
 27.3629 +   responses.
 27.3630 +
 27.3631 +   Clients can ensure that they do not have gaps in lists of articles or
 27.3632 +   groups by using the DATE command in the following manner:
 27.3633 +
 27.3634 +   First session:
 27.3635 +      Issue DATE command and record result.
 27.3636 +      Issue NEWNEWS command using a previously chosen timestamp.
 27.3637 +
 27.3638 +
 27.3639 +
 27.3640 +Feather                     Standards Track                    [Page 65]
 27.3641 +
 27.3642 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3643 +
 27.3644 +
 27.3645 +   Subsequent sessions:
 27.3646 +      Issue DATE command and hold result in temporary storage.
 27.3647 +      Issue NEWNEWS command using timestamp saved from previous session.
 27.3648 +      Overwrite saved timestamp with that currently in temporary
 27.3649 +      storage.
 27.3650 +
 27.3651 +   In order to allow for minor errors, clients MAY want to adjust the
 27.3652 +   timestamp back by two or three minutes before using it in NEWNEWS.
 27.3653 +
 27.3654 +7.5.1.  Examples
 27.3655 +
 27.3656 +   First session:
 27.3657 +
 27.3658 +      [C] DATE
 27.3659 +      [S] 111 20010203112233
 27.3660 +      [C] NEWNEWS local.chat 20001231 235959 GMT
 27.3661 +      [S] 230 list follows
 27.3662 +      [S] <article.1@local.service>
 27.3663 +      [S] <article.2@local.service>
 27.3664 +      [S] <article.3@local.service>
 27.3665 +      [S] .
 27.3666 +
 27.3667 +   Second session (the client has subtracted 3 minutes from the
 27.3668 +   timestamp returned previously):
 27.3669 +
 27.3670 +      [C] DATE
 27.3671 +      [S] 111 20010204003344
 27.3672 +      [C] NEWNEWS local.chat 20010203 111933 GMT
 27.3673 +      [S] 230 list follows
 27.3674 +      [S] <article.3@local.service>
 27.3675 +      [S] <article.4@local.service>
 27.3676 +      [S] <article.5@local.service>
 27.3677 +      [S] .
 27.3678 +
 27.3679 +   Note how <article.3@local.service> arrived in the 3 minute gap and so
 27.3680 +   is listed in both responses.
 27.3681 +
 27.3682 +7.6.  The LIST Commands
 27.3683 +
 27.3684 +   The LIST family of commands all return information that is multi-line
 27.3685 +   and that can, in general, be expected not to change during the
 27.3686 +   session.  Often the information is related to newsgroups, in which
 27.3687 +   case the response has one line per newsgroup and a wildmat MAY be
 27.3688 +   provided to restrict the groups for which information is returned.
 27.3689 +
 27.3690 +   The set of available keywords (including those provided by
 27.3691 +   extensions) is given in the capability list with capability label
 27.3692 +   LIST.
 27.3693 +
 27.3694 +
 27.3695 +
 27.3696 +Feather                     Standards Track                    [Page 66]
 27.3697 +
 27.3698 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3699 +
 27.3700 +
 27.3701 +7.6.1.  LIST
 27.3702 +
 27.3703 +7.6.1.1.  Usage
 27.3704 +
 27.3705 +   Indicating capability: LIST
 27.3706 +
 27.3707 +   Syntax
 27.3708 +     LIST [keyword [wildmat|argument]]
 27.3709 +
 27.3710 +   Responses
 27.3711 +     215    Information follows (multi-line)
 27.3712 +
 27.3713 +   Parameters
 27.3714 +     keyword     Information requested [1]
 27.3715 +     argument    Specific to keyword
 27.3716 +     wildmat     Groups of interest
 27.3717 +
 27.3718 +   [1] If no keyword is provided, it defaults to ACTIVE.
 27.3719 +
 27.3720 +7.6.1.2.  Description
 27.3721 +
 27.3722 +   The LIST command allows the server to provide blocks of information
 27.3723 +   to the client.  This information may be global or may be related to
 27.3724 +   newsgroups; in the latter case, the information may be returned
 27.3725 +   either for all groups or only for those matching a wildmat.  Each
 27.3726 +   block of information is represented by a different keyword.  The
 27.3727 +   command returns the specific information identified by the keyword.
 27.3728 +
 27.3729 +   If the information is available, it is returned as a multi-line data
 27.3730 +   block following the 215 response code.  The format of the information
 27.3731 +   depends on the keyword.  The information MAY be affected by the
 27.3732 +   additional argument, but the format MUST NOT be.
 27.3733 +
 27.3734 +   If the information is based on newsgroups and the optional wildmat
 27.3735 +   argument is specified, the response is limited to only the groups (if
 27.3736 +   any) whose names match the wildmat and for which the information is
 27.3737 +   available.
 27.3738 +
 27.3739 +   Note that an empty list is a possible valid response; for a
 27.3740 +   newsgroup-based keyword, it indicates that there are no groups
 27.3741 +   meeting the above criteria.
 27.3742 +
 27.3743 +   If the keyword is not recognised, or if an argument is specified and
 27.3744 +   the keyword does not expect one, a 501 response code MUST BE
 27.3745 +   returned.  If the keyword is recognised but the server does not
 27.3746 +   maintain the information, a 503 response code MUST BE returned.
 27.3747 +
 27.3748 +
 27.3749 +
 27.3750 +
 27.3751 +
 27.3752 +Feather                     Standards Track                    [Page 67]
 27.3753 +
 27.3754 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3755 +
 27.3756 +
 27.3757 +   The LIST command MUST NOT change the visible state of the server in
 27.3758 +   any way; that is, the behaviour of subsequent commands MUST NOT be
 27.3759 +   affected by whether the LIST command was issued.  For example, it
 27.3760 +   MUST NOT make groups available that otherwise would not have been.
 27.3761 +
 27.3762 +7.6.1.3.  Examples
 27.3763 +
 27.3764 +   Example of LIST with the ACTIVE keyword:
 27.3765 +
 27.3766 +      [C] LIST ACTIVE
 27.3767 +      [S] 215 list of newsgroups follows
 27.3768 +      [S] misc.test 3002322 3000234 y
 27.3769 +      [S] comp.risks 442001 441099 m
 27.3770 +      [S] alt.rfc-writers.recovery 4 1 y
 27.3771 +      [S] tx.natives.recovery 89 56 y
 27.3772 +      [S] tx.natives.recovery.d 11 9 n
 27.3773 +      [S] .
 27.3774 +
 27.3775 +   Example of LIST with no keyword:
 27.3776 +
 27.3777 +      [C] LIST
 27.3778 +      [S] 215 list of newsgroups follows
 27.3779 +      [S] misc.test 3002322 3000234 y
 27.3780 +      [S] comp.risks 442001 441099 m
 27.3781 +      [S] alt.rfc-writers.recovery 4 1 y
 27.3782 +      [S] tx.natives.recovery 89 56 y
 27.3783 +      [S] tx.natives.recovery.d 11 9 n
 27.3784 +      [S] .
 27.3785 +
 27.3786 +   The output is identical to that of the previous example.
 27.3787 +
 27.3788 +   Example of LIST on a newsgroup-based keyword with and without
 27.3789 +   wildmat:
 27.3790 +
 27.3791 +      [C] LIST ACTIVE.TIMES
 27.3792 +      [S] 215 information follows
 27.3793 +      [S] misc.test 930445408 <creatme@isc.org>
 27.3794 +      [S] alt.rfc-writers.recovery 930562309 <m@example.com>
 27.3795 +      [S] tx.natives.recovery 930678923 <sob@academ.com>
 27.3796 +      [S] .
 27.3797 +      [C] LIST ACTIVE.TIMES tx.*
 27.3798 +      [S] 215 information follows
 27.3799 +      [S] tx.natives.recovery 930678923 <sob@academ.com>
 27.3800 +      [S] .
 27.3801 +
 27.3802 +
 27.3803 +
 27.3804 +
 27.3805 +
 27.3806 +
 27.3807 +
 27.3808 +Feather                     Standards Track                    [Page 68]
 27.3809 +
 27.3810 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3811 +
 27.3812 +
 27.3813 +   Example of LIST returning an error where the keyword is recognized
 27.3814 +   but the software does not maintain this information:
 27.3815 +
 27.3816 +      [C] CAPABILITIES
 27.3817 +      [S] 101 Capability list:
 27.3818 +      [S] VERSION 2
 27.3819 +      [S] READER
 27.3820 +      [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA
 27.3821 +      [S] .
 27.3822 +      [C] LIST XTRA.DATA
 27.3823 +      [S] 503 Data item not stored
 27.3824 +
 27.3825 +   Example of LIST where the keyword is not recognised:
 27.3826 +
 27.3827 +      [C] CAPABILITIES
 27.3828 +      [S] 101 Capability list:
 27.3829 +      [S] VERSION 2
 27.3830 +      [S] READER
 27.3831 +      [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA
 27.3832 +      [S] .
 27.3833 +      [C] LIST DISTRIB.PATS
 27.3834 +      [S] 501 Syntax Error
 27.3835 +
 27.3836 +7.6.2.  Standard LIST Keywords
 27.3837 +
 27.3838 +   This specification defines the following LIST keywords:
 27.3839 +
 27.3840 +   +--------------+---------------+------------------------------------+
 27.3841 +   | Keyword      | Definition    | Status                             |
 27.3842 +   +--------------+---------------+------------------------------------+
 27.3843 +   | ACTIVE       | Section 7.6.3 | Mandatory if the READER capability |
 27.3844 +   |              |               | is advertised                      |
 27.3845 +   |              |               |                                    |
 27.3846 +   | ACTIVE.TIMES | Section 7.6.4 | Optional                           |
 27.3847 +   |              |               |                                    |
 27.3848 +   | DISTRIB.PATS | Section 7.6.5 | Optional                           |
 27.3849 +   |              |               |                                    |
 27.3850 +   | HEADERS      | Section 8.6   | Mandatory if the HDR capability is |
 27.3851 +   |              |               | advertised                         |
 27.3852 +   |              |               |                                    |
 27.3853 +   | NEWSGROUPS   | Section 7.6.6 | Mandatory if the READER capability |
 27.3854 +   |              |               | is advertised                      |
 27.3855 +   |              |               |                                    |
 27.3856 +   | OVERVIEW.FMT | Section 8.4   | Mandatory if the OVER capability   |
 27.3857 +   |              |               | is advertised                      |
 27.3858 +   +--------------+---------------+------------------------------------+
 27.3859 +
 27.3860 +
 27.3861 +
 27.3862 +
 27.3863 +
 27.3864 +Feather                     Standards Track                    [Page 69]
 27.3865 +
 27.3866 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3867 +
 27.3868 +
 27.3869 +   Where one of these LIST keywords is supported by a server, it MUST
 27.3870 +   have the meaning given in the relevant sub-section.
 27.3871 +
 27.3872 +7.6.3.  LIST ACTIVE
 27.3873 +
 27.3874 +   This keyword MUST be supported by servers advertising the READER
 27.3875 +   capability.
 27.3876 +
 27.3877 +   LIST ACTIVE returns a list of valid newsgroups and associated
 27.3878 +   information.  If no wildmat is specified, the server MUST include
 27.3879 +   every group that the client is permitted to select with the GROUP
 27.3880 +   command (Section 6.1.1).  Each line of this list consists of four
 27.3881 +   fields separated from each other by one or more spaces:
 27.3882 +
 27.3883 +   o  The name of the newsgroup.
 27.3884 +   o  The reported high water mark for the group.
 27.3885 +   o  The reported low water mark for the group.
 27.3886 +   o  The current status of the group on this server.
 27.3887 +
 27.3888 +   The reported high and low water marks are as described in the GROUP
 27.3889 +   command (see Section 6.1.1), but note that they are in the opposite
 27.3890 +   order to the 211 response to that command.
 27.3891 +
 27.3892 +   The status field is typically one of the following:
 27.3893 +
 27.3894 +   "y" Posting is permitted.
 27.3895 +
 27.3896 +   "n" Posting is not permitted.
 27.3897 +
 27.3898 +   "m" Postings will be forwarded to the newsgroup moderator.
 27.3899 +
 27.3900 +   The server SHOULD use these values when these meanings are required
 27.3901 +   and MUST NOT use them with any other meaning.  Other values for the
 27.3902 +   status may exist; the definition of these other values and the
 27.3903 +   circumstances under which they are returned may be specified in an
 27.3904 +   extension or may be private to the server.  A client SHOULD treat an
 27.3905 +   unrecognized status as giving no information.
 27.3906 +
 27.3907 +   The status of a newsgroup only indicates how posts to that newsgroup
 27.3908 +   are normally processed and is not necessarily customised to the
 27.3909 +   specific client.  For example, if the current client is forbidden
 27.3910 +   from posting, then this will apply equally to groups with status "y".
 27.3911 +   Conversely, a client with special privileges (not defined by this
 27.3912 +   specification) might be able to post to a group with status "n".
 27.3913 +
 27.3914 +
 27.3915 +
 27.3916 +
 27.3917 +
 27.3918 +
 27.3919 +
 27.3920 +Feather                     Standards Track                    [Page 70]
 27.3921 +
 27.3922 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3923 +
 27.3924 +
 27.3925 +   For example:
 27.3926 +
 27.3927 +      [C] LIST ACTIVE
 27.3928 +      [S] 215 list of newsgroups follows
 27.3929 +      [S] misc.test 3002322 3000234 y
 27.3930 +      [S] comp.risks 442001 441099 m
 27.3931 +      [S] alt.rfc-writers.recovery 4 1 y
 27.3932 +      [S] tx.natives.recovery 89 56 y
 27.3933 +      [S] tx.natives.recovery.d 11 9 n
 27.3934 +      [S] .
 27.3935 +
 27.3936 +   or, on an implementation that includes leading zeroes:
 27.3937 +
 27.3938 +      [C] LIST ACTIVE
 27.3939 +      [S] 215 list of newsgroups follows
 27.3940 +      [S] misc.test 0003002322 0003000234 y
 27.3941 +      [S] comp.risks 0000442001 0000441099 m
 27.3942 +      [S] alt.rfc-writers.recovery 0000000004 0000000001 y
 27.3943 +      [S] tx.natives.recovery 0000000089 0000000056 y
 27.3944 +      [S] tx.natives.recovery.d 0000000011 0000000009 n
 27.3945 +      [S] .
 27.3946 +
 27.3947 +   The information is newsgroup based, and a wildmat MAY be specified,
 27.3948 +   in which case the response is limited to only the groups (if any)
 27.3949 +   whose names match the wildmat.  For example:
 27.3950 +
 27.3951 +      [C] LIST ACTIVE *.recovery
 27.3952 +      [S] 215 list of newsgroups follows
 27.3953 +      [S] alt.rfc-writers.recovery 4 1 y
 27.3954 +      [S] tx.natives.recovery 89 56 y
 27.3955 +      [S] .
 27.3956 +
 27.3957 +7.6.4.  LIST ACTIVE.TIMES
 27.3958 +
 27.3959 +   This keyword is optional.
 27.3960 +
 27.3961 +   The active.times list is maintained by some NNTP servers to contain
 27.3962 +   information about who created a particular newsgroup and when.  Each
 27.3963 +   line of this list consists of three fields separated from each other
 27.3964 +   by one or more spaces.  The first field is the name of the newsgroup.
 27.3965 +   The second is the time when this group was created on this news
 27.3966 +   server, measured in seconds since the start of January 1, 1970.  The
 27.3967 +   third is plain text intended to describe the entity that created the
 27.3968 +   newsgroup; it is often a mailbox as defined in RFC 2822 [RFC2822].
 27.3969 +   For example:
 27.3970 +
 27.3971 +
 27.3972 +
 27.3973 +
 27.3974 +
 27.3975 +
 27.3976 +Feather                     Standards Track                    [Page 71]
 27.3977 +
 27.3978 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.3979 +
 27.3980 +
 27.3981 +      [C] LIST ACTIVE.TIMES
 27.3982 +      [S] 215 information follows
 27.3983 +      [S] misc.test 930445408 <creatme@isc.org>
 27.3984 +      [S] alt.rfc-writers.recovery 930562309 <m@example.com>
 27.3985 +      [S] tx.natives.recovery 930678923 <sob@academ.com>
 27.3986 +      [S] .
 27.3987 +
 27.3988 +   The list MAY omit newsgroups for which the information is unavailable
 27.3989 +   and MAY include groups not available on the server; in particular, it
 27.3990 +   MAY omit all groups created before the date and time of the oldest
 27.3991 +   entry.  The client MUST NOT assume that the list is complete or that
 27.3992 +   it matches the list returned by the LIST ACTIVE command
 27.3993 +   (Section 7.6.3).  The NEWGROUPS command (Section 7.3) may provide a
 27.3994 +   better way to access this information, and the results of the two
 27.3995 +   commands SHOULD be consistent except that, if the latter is invoked
 27.3996 +   with a date and time earlier than the oldest entry in active.times
 27.3997 +   list, its result may include extra groups.
 27.3998 +
 27.3999 +   The information is newsgroup based, and a wildmat MAY be specified,
 27.4000 +   in which case the response is limited to only the groups (if any)
 27.4001 +   whose names match the wildmat.
 27.4002 +
 27.4003 +7.6.5.  LIST DISTRIB.PATS
 27.4004 +
 27.4005 +   This keyword is optional.
 27.4006 +
 27.4007 +   The distrib.pats list is maintained by some NNTP servers to assist
 27.4008 +   clients to choose a value for the content of the Distribution header
 27.4009 +   of a news article being posted.  Each line of this list consists of
 27.4010 +   three fields separated from each other by a colon (":").  The first
 27.4011 +   field is a weight, the second field is a wildmat (which may be a
 27.4012 +   simple newsgroup name), and the third field is a value for the
 27.4013 +   Distribution header content.  For example:
 27.4014 +
 27.4015 +      [C] LIST DISTRIB.PATS
 27.4016 +      [S] 215 information follows
 27.4017 +      [S] 10:local.*:local
 27.4018 +      [S] 5:*:world
 27.4019 +      [S] 20:local.here.*:thissite
 27.4020 +      [S] .
 27.4021 +
 27.4022 +   The client MAY use this information to construct an appropriate
 27.4023 +   Distribution header given the name of a newsgroup.  To do so, it
 27.4024 +   should determine the lines whose second field matches the newsgroup
 27.4025 +   name, select from among them the line with the highest weight (with 0
 27.4026 +   being the lowest), and use the value of the third field to construct
 27.4027 +   the Distribution header.
 27.4028 +
 27.4029 +
 27.4030 +
 27.4031 +
 27.4032 +Feather                     Standards Track                    [Page 72]
 27.4033 +
 27.4034 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4035 +
 27.4036 +
 27.4037 +   The information is not newsgroup based, and an argument MUST NOT be
 27.4038 +   specified.
 27.4039 +
 27.4040 +7.6.6.  LIST NEWSGROUPS
 27.4041 +
 27.4042 +   This keyword MUST be supported by servers advertising the READER
 27.4043 +   capability.
 27.4044 +
 27.4045 +   The newsgroups list is maintained by NNTP servers to contain the name
 27.4046 +   of each newsgroup that is available on the server and a short
 27.4047 +   description about the purpose of the group.  Each line of this list
 27.4048 +   consists of two fields separated from each other by one or more space
 27.4049 +   or TAB characters (the usual practice is a single TAB).  The first
 27.4050 +   field is the name of the newsgroup, and the second is a short
 27.4051 +   description of the group.  For example:
 27.4052 +
 27.4053 +      [C] LIST NEWSGROUPS
 27.4054 +      [S] 215 information follows
 27.4055 +      [S] misc.test General Usenet testing
 27.4056 +      [S] alt.rfc-writers.recovery RFC Writers Recovery
 27.4057 +      [S] tx.natives.recovery Texas Natives Recovery
 27.4058 +      [S] .
 27.4059 +
 27.4060 +   The list MAY omit newsgroups for which the information is unavailable
 27.4061 +   and MAY include groups not available on the server.  The client MUST
 27.4062 +   NOT assume that the list is complete or that it matches the list
 27.4063 +   returned by LIST ACTIVE.
 27.4064 +
 27.4065 +   The description SHOULD be in UTF-8.  However, servers often obtain
 27.4066 +   the information from external sources.  These sources may have used
 27.4067 +   different encodings (ones that use octets in the range 128 to 255 in
 27.4068 +   some other manner) and, in that case, the server MAY pass it on
 27.4069 +   unchanged.  Therefore, clients MUST be prepared to receive such
 27.4070 +   descriptions.
 27.4071 +
 27.4072 +   The information is newsgroup based, and a wildmat MAY be specified,
 27.4073 +   in which case the response is limited to only the groups (if any)
 27.4074 +   whose names match the wildmat.
 27.4075 +
 27.4076 +8.  Article Field Access Commands
 27.4077 +
 27.4078 +   This section lists commands that may be used to access specific
 27.4079 +   article fields; that is, headers of articles and metadata about
 27.4080 +   articles.  These commands typically fetch data from an "overview
 27.4081 +   database", which is a database of headers extracted from incoming
 27.4082 +   articles plus metadata determined as the article arrives.  Only
 27.4083 +   certain fields are included in the database.
 27.4084 +
 27.4085 +
 27.4086 +
 27.4087 +
 27.4088 +Feather                     Standards Track                    [Page 73]
 27.4089 +
 27.4090 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4091 +
 27.4092 +
 27.4093 +   This section is based on the Overview/NOV database [ROBE1995]
 27.4094 +   developed by Geoff Collyer.
 27.4095 +
 27.4096 +8.1.  Article Metadata
 27.4097 +
 27.4098 +   Article "metadata" is data about articles that does not occur within
 27.4099 +   the article itself.  Each metadata item has a name that MUST begin
 27.4100 +   with a colon (and that MUST NOT contain a colon elsewhere within it).
 27.4101 +   As with header names, metadata item names are not case sensitive.
 27.4102 +
 27.4103 +   When generating a metadata item, the server MUST compute it for
 27.4104 +   itself and MUST NOT trust any related value provided in the article.
 27.4105 +   (In particular, a Lines or Bytes header in the article MUST NOT be
 27.4106 +   assumed to specify the correct number of lines or bytes in the
 27.4107 +   article.)  If the server has access to several non-identical copies
 27.4108 +   of an article, the value returned MUST be correct for any copy of
 27.4109 +   that article retrieved during the same session.
 27.4110 +
 27.4111 +   This specification defines two metadata items: ":bytes" and ":lines".
 27.4112 +   Other metadata items may be defined by extensions.  The names of
 27.4113 +   metadata items defined by registered extensions MUST NOT begin with
 27.4114 +   ":x-".  To avoid the risk of a clash with a future registered
 27.4115 +   extension, the names of metadata items defined by private extensions
 27.4116 +   SHOULD begin with ":x-".
 27.4117 +
 27.4118 +8.1.1.  The :bytes Metadata Item
 27.4119 +
 27.4120 +   The :bytes metadata item for an article is a decimal integer.  It
 27.4121 +   SHOULD equal the number of octets in the entire article: headers,
 27.4122 +   body, and separating empty line (counting a CRLF pair as two octets,
 27.4123 +   and excluding both the "." CRLF terminating the response and any "."
 27.4124 +   added for "dot-stuffing" purposes).
 27.4125 +
 27.4126 +   Note to client implementers: some existing servers return a value
 27.4127 +   different from that above.  The commonest reasons for this are as
 27.4128 +   follows:
 27.4129 +
 27.4130 +   o  Counting a CRLF pair as one octet.
 27.4131 +
 27.4132 +   o  Including the "." character used for dot-stuffing in the number.
 27.4133 +
 27.4134 +   o  Including the terminating "." CRLF in the number.
 27.4135 +
 27.4136 +   o  Using one copy of an article for counting the octets but then
 27.4137 +      returning another one that differs in some (permitted) manner.
 27.4138 +
 27.4139 +   Implementations should be prepared for such variation and MUST NOT
 27.4140 +   rely on the value being accurate.
 27.4141 +
 27.4142 +
 27.4143 +
 27.4144 +Feather                     Standards Track                    [Page 74]
 27.4145 +
 27.4146 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4147 +
 27.4148 +
 27.4149 +8.1.2.  The :lines Metadata Item
 27.4150 +
 27.4151 +   The :lines metadata item for an article is a decimal integer.  It
 27.4152 +   MUST equal the number of lines in the article body (excluding the
 27.4153 +   empty line separating headers and body).  Equivalently, it is two
 27.4154 +   less than the number of CRLF pairs that the BODY command would return
 27.4155 +   for that article (the extra two are those following the response code
 27.4156 +   and the termination octet).
 27.4157 +
 27.4158 +8.2.  Database Consistency
 27.4159 +
 27.4160 +   The information stored in the overview database may change over time.
 27.4161 +   If the database records the content or absence of a given field (that
 27.4162 +   is, a header or metadata item) for all articles, it is said to be
 27.4163 +   "consistent" for that field.  If it records the content of a header
 27.4164 +   for some articles but not for others that nevertheless included that
 27.4165 +   header, or if it records a metadata item for some articles but not
 27.4166 +   for others to which that item applies, it is said to be
 27.4167 +   "inconsistent" for that field.
 27.4168 +
 27.4169 +   The LIST OVERVIEW.FMT command SHOULD list all the fields for which
 27.4170 +   the database is consistent at that moment.  It MAY omit such fields
 27.4171 +   (for example, if it is not known whether the database is consistent
 27.4172 +   or inconsistent).  It MUST NOT include fields for which the database
 27.4173 +   is inconsistent or that are not stored in the database.  Therefore,
 27.4174 +   if a header appears in the LIST OVERVIEW.FMT output but not in the
 27.4175 +   OVER output for a given article, that header does not appear in the
 27.4176 +   article (similarly for metadata items).
 27.4177 +
 27.4178 +   These rules assume that the fields being stored in the database
 27.4179 +   remain constant for long periods of time, and therefore the database
 27.4180 +   will be consistent.  When the set of fields to be stored is changed,
 27.4181 +   it will be inconsistent until either the database is rebuilt or the
 27.4182 +   only articles remaining are those received since the change.
 27.4183 +   Therefore, the output from LIST OVERVIEW.FMT needs to be altered
 27.4184 +   twice.  Firstly, before any fields stop being stored they MUST be
 27.4185 +   removed from the output; then, when the database is once more known
 27.4186 +   to be consistent, the new fields SHOULD be added to the output.
 27.4187 +
 27.4188 +   If the HDR command uses the overview database rather than taking
 27.4189 +   information directly from the articles, the same issues of
 27.4190 +   consistency and inconsistency apply, and the LIST HEADERS command
 27.4191 +   SHOULD take the same approach as the LIST OVERVIEW.FMT command in
 27.4192 +   resolving them.
 27.4193 +
 27.4194 +
 27.4195 +
 27.4196 +
 27.4197 +
 27.4198 +
 27.4199 +
 27.4200 +Feather                     Standards Track                    [Page 75]
 27.4201 +
 27.4202 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4203 +
 27.4204 +
 27.4205 +8.3.  OVER
 27.4206 +
 27.4207 +8.3.1.  Usage
 27.4208 +
 27.4209 +   Indicating capability: OVER
 27.4210 +
 27.4211 +   Syntax
 27.4212 +     OVER message-id
 27.4213 +     OVER range
 27.4214 +     OVER
 27.4215 +
 27.4216 +   Responses
 27.4217 +
 27.4218 +   First form (message-id specified)
 27.4219 +     224    Overview information follows (multi-line)
 27.4220 +     430    No article with that message-id
 27.4221 +
 27.4222 +   Second form (range specified)
 27.4223 +     224    Overview information follows (multi-line)
 27.4224 +     412    No newsgroup selected
 27.4225 +     423    No articles in that range
 27.4226 +
 27.4227 +   Third form (current article number used)
 27.4228 +     224    Overview information follows (multi-line)
 27.4229 +     412    No newsgroup selected
 27.4230 +     420    Current article number is invalid
 27.4231 +
 27.4232 +   Parameters
 27.4233 +     range         Number(s) of articles
 27.4234 +     message-id    Message-id of article
 27.4235 +
 27.4236 +8.3.2.  Description
 27.4237 +
 27.4238 +   The OVER command returns the contents of all the fields in the
 27.4239 +   database for an article specified by message-id, or from a specified
 27.4240 +   article or range of articles in the currently selected newsgroup.
 27.4241 +
 27.4242 +   The message-id argument indicates a specific article.  The range
 27.4243 +   argument may be any of the following:
 27.4244 +
 27.4245 +   o  An article number.
 27.4246 +
 27.4247 +   o  An article number followed by a dash to indicate all following.
 27.4248 +
 27.4249 +   o  An article number followed by a dash followed by another article
 27.4250 +      number.
 27.4251 +
 27.4252 +   If neither is specified, the current article number is used.
 27.4253 +
 27.4254 +
 27.4255 +
 27.4256 +Feather                     Standards Track                    [Page 76]
 27.4257 +
 27.4258 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4259 +
 27.4260 +
 27.4261 +   Support for the first (message-id) form is optional.  If it is
 27.4262 +   supported, the OVER capability line MUST include the argument
 27.4263 +   "MSGID".  Otherwise, the capability line MUST NOT include this
 27.4264 +   argument, and the OVER command MUST return the generic response code
 27.4265 +   503 when this form is used.
 27.4266 +
 27.4267 +   If the information is available, it is returned as a multi-line data
 27.4268 +   block following the 224 response code and contains one line per
 27.4269 +   article, sorted in numerical order of article number.  (Note that
 27.4270 +   unless the argument is a range including a dash, there will be
 27.4271 +   exactly one line in the data block.)  Each line consists of a number
 27.4272 +   of fields separated by a TAB.  A field may be empty (in which case
 27.4273 +   there will be two adjacent TABs), and a sequence of trailing TABs may
 27.4274 +   be omitted.
 27.4275 +
 27.4276 +   The first 8 fields MUST be the following, in order:
 27.4277 +
 27.4278 +      "0" or article number (see below)
 27.4279 +      Subject header content
 27.4280 +      From header content
 27.4281 +      Date header content
 27.4282 +      Message-ID header content
 27.4283 +      References header content
 27.4284 +      :bytes metadata item
 27.4285 +      :lines metadata item
 27.4286 +
 27.4287 +   If the article is specified by message-id (the first form of the
 27.4288 +   command), the article number MUST be replaced with zero, except that
 27.4289 +   if there is a currently selected newsgroup and the article is present
 27.4290 +   in that group, the server MAY use the article's number in that group.
 27.4291 +   (See the ARTICLE command (Section 6.2.1) and STAT examples
 27.4292 +   (Section 6.2.4.3) for more details.)  In the other two forms of the
 27.4293 +   command, the article number MUST be returned.
 27.4294 +
 27.4295 +   Any subsequent fields are the contents of the other headers and
 27.4296 +   metadata held in the database.
 27.4297 +
 27.4298 +   For the five mandatory headers, the content of each field MUST be
 27.4299 +   based on the content of the header (that is, with the header name and
 27.4300 +   following colon and space removed).  If the article does not contain
 27.4301 +   that header, or if the content is empty, the field MUST be empty.
 27.4302 +   For the two mandatory metadata items, the content of the field MUST
 27.4303 +   be just the value, with no other text.
 27.4304 +
 27.4305 +   For all subsequent fields that contain headers, the content MUST be
 27.4306 +   the entire header line other than the trailing CRLF.  For all
 27.4307 +   subsequent fields that contain metadata, the field consists of the
 27.4308 +   metadata name, a single space, and then the value.
 27.4309 +
 27.4310 +
 27.4311 +
 27.4312 +Feather                     Standards Track                    [Page 77]
 27.4313 +
 27.4314 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4315 +
 27.4316 +
 27.4317 +   For all fields, the value is processed by first removing all CRLF
 27.4318 +   pairs (that is, undoing any folding and removing the terminating
 27.4319 +   CRLF) and then replacing each TAB with a single space.  If there is
 27.4320 +   no such header in the article, no such metadata item, or no header or
 27.4321 +   item stored in the database for that article, the corresponding field
 27.4322 +   MUST be empty.
 27.4323 +
 27.4324 +   Note that, after unfolding, the characters NUL, LF, and CR cannot
 27.4325 +   occur in the header of an article offered by a conformant server.
 27.4326 +   Nevertheless, servers SHOULD check for these characters and replace
 27.4327 +   each one by a single space (so that, for example, CR LF LF TAB will
 27.4328 +   become two spaces, since the CR and first LF will be removed by the
 27.4329 +   unfolding process).  This will encourage robustness in the face of
 27.4330 +   non-conforming data; it is also possible that future versions of this
 27.4331 +   specification could permit these characters to appear in articles.
 27.4332 +
 27.4333 +   The server SHOULD NOT produce output for articles that no longer
 27.4334 +   exist.
 27.4335 +
 27.4336 +   If the argument is a message-id and no such article exists, a 430
 27.4337 +   response MUST be returned.  If the argument is a range or is omitted
 27.4338 +   and the currently selected newsgroup is invalid, a 412 response MUST
 27.4339 +   be returned.  If the argument is a range and no articles in that
 27.4340 +   number range exist in the currently selected newsgroup, including the
 27.4341 +   case where the second number is less than the first one, a 423
 27.4342 +   response MUST be returned.  If the argument is omitted and the
 27.4343 +   current article number is invalid, a 420 response MUST be returned.
 27.4344 +
 27.4345 +8.3.3.  Examples
 27.4346 +
 27.4347 +   In the first four examples, TAB has been replaced by vertical bar and
 27.4348 +   some lines have been folded for readability.
 27.4349 +
 27.4350 +   Example of a successful retrieval of overview information for an
 27.4351 +   article (explicitly not using an article number):
 27.4352 +
 27.4353 +      [C] GROUP misc.test
 27.4354 +      [S] 211 1234 3000234 3002322 misc.test
 27.4355 +      [C] OVER
 27.4356 +      [S] 224 Overview information follows
 27.4357 +      [S] 3000234|I am just a test article|"Demo User"
 27.4358 +          <nobody@example.com>|6 Oct 1998 04:38:40 -0500|
 27.4359 +          <45223423@example.com>|<45454@example.net>|1234|
 27.4360 +          17|Xref: news.example.com misc.test:3000363
 27.4361 +      [S] .
 27.4362 +
 27.4363 +
 27.4364 +
 27.4365 +
 27.4366 +
 27.4367 +
 27.4368 +Feather                     Standards Track                    [Page 78]
 27.4369 +
 27.4370 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4371 +
 27.4372 +
 27.4373 +   Example of a successful retrieval of overview information for an
 27.4374 +   article by message-id:
 27.4375 +
 27.4376 +      [C] CAPABILITIES
 27.4377 +      [S] 101 Capability list:
 27.4378 +      [S] VERSION 2
 27.4379 +      [S] READER
 27.4380 +      [S] OVER MSGID
 27.4381 +      [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT
 27.4382 +      [S] .
 27.4383 +      [C] OVER <45223423@example.com>
 27.4384 +      [S] 224 Overview information follows
 27.4385 +      [S] 0|I am just a test article|"Demo User"
 27.4386 +          <nobody@example.com>|6 Oct 1998 04:38:40 -0500|
 27.4387 +          <45223423@example.com>|<45454@example.net>|1234|
 27.4388 +          17|Xref: news.example.com misc.test:3000363
 27.4389 +      [S] .
 27.4390 +
 27.4391 +   Note that the article number has been replaced by "0".
 27.4392 +
 27.4393 +   Example of the same commands on a system that does not implement
 27.4394 +   retrieval by message-id:
 27.4395 +
 27.4396 +      [C] CAPABILITIES
 27.4397 +      [S] 101 Capability list:
 27.4398 +      [S] VERSION 2
 27.4399 +      [S] READER
 27.4400 +      [S] OVER
 27.4401 +      [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT
 27.4402 +      [S] .
 27.4403 +      [C] OVER <45223423@example.com>
 27.4404 +      [S] 503 Overview by message-id unsupported
 27.4405 +
 27.4406 +
 27.4407 +
 27.4408 +
 27.4409 +
 27.4410 +
 27.4411 +
 27.4412 +
 27.4413 +
 27.4414 +
 27.4415 +
 27.4416 +
 27.4417 +
 27.4418 +
 27.4419 +
 27.4420 +
 27.4421 +
 27.4422 +
 27.4423 +
 27.4424 +Feather                     Standards Track                    [Page 79]
 27.4425 +
 27.4426 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4427 +
 27.4428 +
 27.4429 +   Example of a successful retrieval of overview information for a range
 27.4430 +   of articles:
 27.4431 +
 27.4432 +      [C] GROUP misc.test
 27.4433 +      [S] 211 1234 3000234 3002322 misc.test
 27.4434 +      [C] OVER 3000234-3000240
 27.4435 +      [S] 224 Overview information follows
 27.4436 +      [S] 3000234|I am just a test article|"Demo User"
 27.4437 +          <nobody@example.com>|6 Oct 1998 04:38:40 -0500|
 27.4438 +          <45223423@example.com>|<45454@example.net>|1234|
 27.4439 +          17|Xref: news.example.com misc.test:3000363
 27.4440 +      [S] 3000235|Another test article|nobody@nowhere.to
 27.4441 +          (Demo User)|6 Oct 1998 04:38:45 -0500|<45223425@to.to>||
 27.4442 +          4818|37||Distribution: fi
 27.4443 +      [S] 3000238|Re: I am just a test article|somebody@elsewhere.to|
 27.4444 +          7 Oct 1998 11:38:40 +1200|<kfwer3v@elsewhere.to>|
 27.4445 +          <45223423@to.to>|9234|51
 27.4446 +      [S] .
 27.4447 +
 27.4448 +   Note the missing "References" and Xref headers in the second line,
 27.4449 +   the missing trailing fields in the first and last lines, and that
 27.4450 +   there are only results for those articles that still exist.
 27.4451 +
 27.4452 +   Example of an unsuccessful retrieval of overview information on an
 27.4453 +   article by number:
 27.4454 +
 27.4455 +      [C] GROUP misc.test
 27.4456 +      [S] 211 1234 3000234 3002322 misc.test
 27.4457 +      [C] OVER 300256
 27.4458 +      [S] 423 No such article in this group
 27.4459 +
 27.4460 +   Example of an invalid range:
 27.4461 +
 27.4462 +      [C] GROUP misc.test
 27.4463 +      [S] 211 1234 3000234 3002322 misc.test
 27.4464 +      [C] OVER 3000444-3000222
 27.4465 +      [S] 423 Empty range
 27.4466 +
 27.4467 +   Example of an unsuccessful retrieval of overview information by
 27.4468 +   number because no newsgroup was selected first:
 27.4469 +
 27.4470 +      [Assumes currently selected newsgroup is invalid.]
 27.4471 +      [C] OVER
 27.4472 +      [S] 412 No newsgroup selected
 27.4473 +
 27.4474 +
 27.4475 +
 27.4476 +
 27.4477 +
 27.4478 +
 27.4479 +
 27.4480 +Feather                     Standards Track                    [Page 80]
 27.4481 +
 27.4482 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4483 +
 27.4484 +
 27.4485 +   Example of an attempt to retrieve information when the currently
 27.4486 +   selected newsgroup is empty:
 27.4487 +
 27.4488 +      [C] GROUP example.empty.newsgroup
 27.4489 +      [S] 211 0 0 0 example.empty.newsgroup
 27.4490 +      [C] OVER
 27.4491 +      [S] 420 No current article selected
 27.4492 +
 27.4493 +8.4.  LIST OVERVIEW.FMT
 27.4494 +
 27.4495 +8.4.1.  Usage
 27.4496 +
 27.4497 +   Indicating capability: OVER
 27.4498 +
 27.4499 +   Syntax
 27.4500 +     LIST OVERVIEW.FMT
 27.4501 +
 27.4502 +   Responses
 27.4503 +     215    Information follows (multi-line)
 27.4504 +
 27.4505 +8.4.2.  Description
 27.4506 +
 27.4507 +   See Section 7.6.1 for general requirements of the LIST command.
 27.4508 +
 27.4509 +   The LIST OVERVIEW.FMT command returns a description of the fields in
 27.4510 +   the database for which it is consistent (as described above).  The
 27.4511 +   information is returned as a multi-line data block following the 215
 27.4512 +   response code.  The information contains one line per field in the
 27.4513 +   order in which they are returned by the OVER command; the first 7
 27.4514 +   lines MUST (except for the case of letters) be exactly as follows:
 27.4515 +
 27.4516 +       Subject:
 27.4517 +       From:
 27.4518 +       Date:
 27.4519 +       Message-ID:
 27.4520 +       References:
 27.4521 +       :bytes
 27.4522 +       :lines
 27.4523 +
 27.4524 +   For compatibility with existing implementations, the last two lines
 27.4525 +   MAY instead be:
 27.4526 +
 27.4527 +       Bytes:
 27.4528 +       Lines:
 27.4529 +
 27.4530 +   even though they refer to metadata, not headers.
 27.4531 +
 27.4532 +
 27.4533 +
 27.4534 +
 27.4535 +
 27.4536 +Feather                     Standards Track                    [Page 81]
 27.4537 +
 27.4538 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4539 +
 27.4540 +
 27.4541 +   All subsequent lines MUST consist of either a header name followed by
 27.4542 +   ":full", or the name of a piece of metadata.
 27.4543 +
 27.4544 +   There are no leading or trailing spaces in the output.
 27.4545 +
 27.4546 +   Note that the 7 fixed lines describe the 2nd to 8th fields of the
 27.4547 +   OVER output.  The "full" suffix (which may use either uppercase,
 27.4548 +   lowercase, or a mix) is a reminder that the corresponding fields
 27.4549 +   include the header name.
 27.4550 +
 27.4551 +   This command MAY generate different results if it is used more than
 27.4552 +   once in a session.
 27.4553 +
 27.4554 +   If the OVER command is not implemented, the meaning of the output
 27.4555 +   from this command is not specified, but it must still meet the above
 27.4556 +   syntactic requirements.
 27.4557 +
 27.4558 +8.4.3.  Examples
 27.4559 +
 27.4560 +   Example of LIST OVERVIEW.FMT output corresponding to the example OVER
 27.4561 +   output above, in the preferred format:
 27.4562 +
 27.4563 +      [C] LIST OVERVIEW.FMT
 27.4564 +      [S] 215 Order of fields in overview database.
 27.4565 +      [S] Subject:
 27.4566 +      [S] From:
 27.4567 +      [S] Date:
 27.4568 +      [S] Message-ID:
 27.4569 +      [S] References:
 27.4570 +      [S] :bytes
 27.4571 +      [S] :lines
 27.4572 +      [S] Xref:full
 27.4573 +      [S] Distribution:full
 27.4574 +      [S] .
 27.4575 +
 27.4576 +
 27.4577 +
 27.4578 +
 27.4579 +
 27.4580 +
 27.4581 +
 27.4582 +
 27.4583 +
 27.4584 +
 27.4585 +
 27.4586 +
 27.4587 +
 27.4588 +
 27.4589 +
 27.4590 +
 27.4591 +
 27.4592 +Feather                     Standards Track                    [Page 82]
 27.4593 +
 27.4594 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4595 +
 27.4596 +
 27.4597 +   Example of LIST OVERVIEW.FMT output corresponding to the example OVER
 27.4598 +   output above, in the alternative format:
 27.4599 +
 27.4600 +      [C] LIST OVERVIEW.FMT
 27.4601 +      [S] 215 Order of fields in overview database.
 27.4602 +      [S] Subject:
 27.4603 +      [S] From:
 27.4604 +      [S] Date:
 27.4605 +      [S] Message-ID:
 27.4606 +      [S] References:
 27.4607 +      [S] Bytes:
 27.4608 +      [S] Lines:
 27.4609 +      [S] Xref:FULL
 27.4610 +      [S] Distribution:FULL
 27.4611 +      [S] .
 27.4612 +
 27.4613 +8.5.  HDR
 27.4614 +
 27.4615 +8.5.1.  Usage
 27.4616 +
 27.4617 +   Indicating capability: HDR
 27.4618 +
 27.4619 +   Syntax
 27.4620 +     HDR field message-id
 27.4621 +     HDR field range
 27.4622 +     HDR field
 27.4623 +
 27.4624 +   Responses
 27.4625 +
 27.4626 +   First form (message-id specified)
 27.4627 +     225    Headers follow (multi-line)
 27.4628 +     430    No article with that message-id
 27.4629 +
 27.4630 +   Second form (range specified)
 27.4631 +     225    Headers follow (multi-line)
 27.4632 +     412    No newsgroup selected
 27.4633 +     423    No articles in that range
 27.4634 +
 27.4635 +   Third form (current article number used)
 27.4636 +     225    Headers follow (multi-line)
 27.4637 +     412    No newsgroup selected
 27.4638 +     420    Current article number is invalid
 27.4639 +
 27.4640 +   Parameters
 27.4641 +     field         Name of field
 27.4642 +     range         Number(s) of articles
 27.4643 +     message-id    Message-id of article
 27.4644 +
 27.4645 +
 27.4646 +
 27.4647 +
 27.4648 +Feather                     Standards Track                    [Page 83]
 27.4649 +
 27.4650 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4651 +
 27.4652 +
 27.4653 +8.5.2.  Description
 27.4654 +
 27.4655 +   The HDR command provides access to specific fields from an article
 27.4656 +   specified by message-id, or from a specified article or range of
 27.4657 +   articles in the currently selected newsgroup.  It MAY take the
 27.4658 +   information directly from the articles or from the overview database.
 27.4659 +   In the case of headers, an implementation MAY restrict the use of
 27.4660 +   this command to a specific list of headers or MAY allow it to be used
 27.4661 +   with any header; it may behave differently when it is used with a
 27.4662 +   message-id argument and when it is used with a range or no argument.
 27.4663 +
 27.4664 +   The required field argument is the name of a header with the colon
 27.4665 +   omitted (e.g., "subject") or the name of a metadata item including
 27.4666 +   the leading colon (e.g., ":bytes"), and is case insensitive.
 27.4667 +
 27.4668 +   The message-id argument indicates a specific article.  The range
 27.4669 +   argument may be any of the following:
 27.4670 +
 27.4671 +   o  An article number.
 27.4672 +
 27.4673 +   o  An article number followed by a dash to indicate all following.
 27.4674 +
 27.4675 +   o  An article number followed by a dash followed by another article
 27.4676 +      number.
 27.4677 +
 27.4678 +   If neither is specified, the current article number is used.
 27.4679 +
 27.4680 +   If the information is available, it is returned as a multi-line data
 27.4681 +   block following the 225 response code and contains one line for each
 27.4682 +   article in the range that exists.  (Note that unless the argument is
 27.4683 +   a range including a dash, there will be exactly one line in the data
 27.4684 +   block.)  The line consists of the article number, a space, and then
 27.4685 +   the contents of the field.  In the case of a header, the header name,
 27.4686 +   the colon, and the first space after the colon are all omitted.
 27.4687 +
 27.4688 +   If the article is specified by message-id (the first form of the
 27.4689 +   command), the article number MUST be replaced with zero, except that
 27.4690 +   if there is a currently selected newsgroup and the article is present
 27.4691 +   in that group, the server MAY use the article's number in that group.
 27.4692 +   (See the ARTICLE command (Section 6.2.1) and STAT examples
 27.4693 +   (Section 6.2.4.3) for more details.)  In the other two forms of the
 27.4694 +   command, the article number MUST be returned.
 27.4695 +
 27.4696 +   Header contents are modified as follows: all CRLF pairs are removed,
 27.4697 +   and then each TAB is replaced with a single space.  (Note that this
 27.4698 +   is the same transformation as is performed by the OVER command
 27.4699 +   (Section 8.3.2), and the same comment concerning NUL, CR, and LF
 27.4700 +   applies.)
 27.4701 +
 27.4702 +
 27.4703 +
 27.4704 +Feather                     Standards Track                    [Page 84]
 27.4705 +
 27.4706 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4707 +
 27.4708 +
 27.4709 +   Note the distinction between headers and metadata appearing to have
 27.4710 +   the same meaning.  Headers are always taken unchanged from the
 27.4711 +   article; metadata are always calculated.  For example, a request for
 27.4712 +   "Lines" returns the contents of the "Lines" header of the specified
 27.4713 +   articles, if any, no matter whether they accurately state the number
 27.4714 +   of lines, while a request for ":lines" returns the line count
 27.4715 +   metadata, which is always the actual number of lines irrespective of
 27.4716 +   what any header may state.
 27.4717 +
 27.4718 +   If the requested header is not present in the article, or if it is
 27.4719 +   present but empty, a line for that article is included in the output,
 27.4720 +   but the header content portion of the line is empty (the space after
 27.4721 +   the article number MAY be retained or omitted).  If the header occurs
 27.4722 +   in a given article more than once, only the content of the first
 27.4723 +   occurrence is returned by HDR.  If any article number in the provided
 27.4724 +   range does not exist in the group, no line for that article number is
 27.4725 +   included in the output.
 27.4726 +
 27.4727 +   If the second argument is a message-id and no such article exists, a
 27.4728 +   430 response MUST be returned.  If the second argument is a range or
 27.4729 +   is omitted and the currently selected newsgroup is invalid, a 412
 27.4730 +   response MUST be returned.  If the second argument is a range and no
 27.4731 +   articles in that number range exist in the currently selected
 27.4732 +   newsgroup, including the case where the second number is less than
 27.4733 +   the first one, a 423 response MUST be returned.  If the second
 27.4734 +   argument is omitted and the current article number is invalid, a 420
 27.4735 +   response MUST be returned.
 27.4736 +
 27.4737 +   A server MAY only allow HDR commands for a limited set of fields; it
 27.4738 +   may behave differently in this respect for the first (message-id)
 27.4739 +   form from how it would for the other forms.  If so, it MUST respond
 27.4740 +   with the generic 503 response to attempts to request other fields,
 27.4741 +   rather than return erroneous results, such as a successful empty
 27.4742 +   response.
 27.4743 +
 27.4744 +   If HDR uses the overview database and it is inconsistent for the
 27.4745 +   requested field, the server MAY return what results it can, or it MAY
 27.4746 +   respond with the generic 503 response.  In the latter case, the field
 27.4747 +   MUST NOT appear in the output from LIST HEADERS.
 27.4748 +
 27.4749 +
 27.4750 +
 27.4751 +
 27.4752 +
 27.4753 +
 27.4754 +
 27.4755 +
 27.4756 +
 27.4757 +
 27.4758 +
 27.4759 +
 27.4760 +Feather                     Standards Track                    [Page 85]
 27.4761 +
 27.4762 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4763 +
 27.4764 +
 27.4765 +8.5.3.  Examples
 27.4766 +
 27.4767 +   Example of a successful retrieval of subject lines from a range of
 27.4768 +   articles (3000235 has no Subject header, and 3000236 is missing):
 27.4769 +
 27.4770 +      [C] GROUP misc.test
 27.4771 +      [S] 211 1234 3000234 3002322 misc.test
 27.4772 +      [C] HDR Subject 3000234-3000238
 27.4773 +      [S] 225 Headers follow
 27.4774 +      [S] 3000234 I am just a test article
 27.4775 +      [S] 3000235
 27.4776 +      [S] 3000237 Re: I am just a test article
 27.4777 +      [S] 3000238 Ditto
 27.4778 +      [S] .
 27.4779 +
 27.4780 +   Example of a successful retrieval of line counts from a range of
 27.4781 +   articles:
 27.4782 +
 27.4783 +      [C] GROUP misc.test
 27.4784 +      [S] 211 1234 3000234 3002322 misc.test
 27.4785 +      [C] HDR :lines 3000234-3000238
 27.4786 +      [S] 225 Headers follow
 27.4787 +      [S] 3000234 42
 27.4788 +      [S] 3000235 5
 27.4789 +      [S] 3000237 11
 27.4790 +      [S] 3000238 2378
 27.4791 +      [S] .
 27.4792 +
 27.4793 +   Example of a successful retrieval of the subject line from an article
 27.4794 +   by message-id:
 27.4795 +
 27.4796 +      [C] GROUP misc.test
 27.4797 +      [S] 211 1234 3000234 3002322 misc.test
 27.4798 +      [C] HDR subject <i.am.a.test.article@example.com>
 27.4799 +      [S] 225 Header information follows
 27.4800 +      [S] 0 I am just a test article
 27.4801 +      [S] .
 27.4802 +
 27.4803 +   Example of a successful retrieval of the subject line from the
 27.4804 +   current article:
 27.4805 +
 27.4806 +      [C] GROUP misc.test
 27.4807 +      [S] 211 1234 3000234 3002322 misc.test
 27.4808 +      [C] HDR subject
 27.4809 +      [S] 225 Header information follows
 27.4810 +      [S] 3000234 I am just a test article
 27.4811 +      [S] .
 27.4812 +
 27.4813 +
 27.4814 +
 27.4815 +
 27.4816 +Feather                     Standards Track                    [Page 86]
 27.4817 +
 27.4818 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4819 +
 27.4820 +
 27.4821 +   Example of an unsuccessful retrieval of a header from an article by
 27.4822 +   message-id:
 27.4823 +
 27.4824 +      [C] HDR subject <i.am.not.there@example.com>
 27.4825 +      [S] 430 No Such Article Found
 27.4826 +
 27.4827 +   Example of an unsuccessful retrieval of headers from articles by
 27.4828 +   number because no newsgroup was selected first:
 27.4829 +
 27.4830 +      [Assumes currently selected newsgroup is invalid.]
 27.4831 +      [C] HDR subject 300256-
 27.4832 +      [S] 412 No newsgroup selected
 27.4833 +
 27.4834 +   Example of an unsuccessful retrieval of headers because the currently
 27.4835 +   selected newsgroup is empty:
 27.4836 +
 27.4837 +      [C] GROUP example.empty.newsgroup
 27.4838 +      [S] 211 0 0 0 example.empty.newsgroup
 27.4839 +      [C] HDR subject 1-
 27.4840 +      [S] 423 No articles in that range
 27.4841 +
 27.4842 +   Example of an unsuccessful retrieval of headers because the server
 27.4843 +   does not allow HDR commands for that header:
 27.4844 +
 27.4845 +      [C] GROUP misc.test
 27.4846 +      [S] 211 1234 3000234 3002322 misc.test
 27.4847 +      [C] HDR Content-Type 3000234-3000238
 27.4848 +      [S] 503 HDR not permitted on Content-Type
 27.4849 +
 27.4850 +8.6.  LIST HEADERS
 27.4851 +
 27.4852 +8.6.1.  Usage
 27.4853 +
 27.4854 +   Indicating capability: HDR
 27.4855 +
 27.4856 +   Syntax
 27.4857 +     LIST HEADERS [MSGID|RANGE]
 27.4858 +
 27.4859 +   Responses
 27.4860 +     215    Field list follows (multi-line)
 27.4861 +
 27.4862 +   Parameters
 27.4863 +     MSGID    Requests list for access by message-id
 27.4864 +     RANGE    Requests list for access by range
 27.4865 +
 27.4866 +
 27.4867 +
 27.4868 +
 27.4869 +
 27.4870 +
 27.4871 +
 27.4872 +Feather                     Standards Track                    [Page 87]
 27.4873 +
 27.4874 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4875 +
 27.4876 +
 27.4877 +8.6.2.  Description
 27.4878 +
 27.4879 +   See Section 7.6.1 for general requirements of the LIST command.
 27.4880 +
 27.4881 +   The LIST HEADERS command returns a list of fields that may be
 27.4882 +   retrieved using the HDR command.
 27.4883 +
 27.4884 +   The information is returned as a multi-line data block following the
 27.4885 +   215 response code and contains one line for each field name
 27.4886 +   (excluding the trailing colon for headers and including the leading
 27.4887 +   colon for metadata items).  If the implementation allows any header
 27.4888 +   to be retrieved, it MUST NOT include any header names in the list but
 27.4889 +   MUST include the special entry ":" (a single colon on its own).  It
 27.4890 +   MUST still explicitly list any metadata items that are available.
 27.4891 +   The order of items in the list is not significant; the server need
 27.4892 +   not even consistently return the same order.  The list MAY be empty
 27.4893 +   (though in this circumstance there is little point in providing the
 27.4894 +   HDR command).
 27.4895 +
 27.4896 +   An implementation that also supports the OVER command SHOULD at least
 27.4897 +   permit all the headers and metadata items listed in the output from
 27.4898 +   the LIST OVERVIEW.FMT command.
 27.4899 +
 27.4900 +   If the server treats the first form of the HDR command (message-id
 27.4901 +   specified) differently from the other two forms (range specified or
 27.4902 +   current article number used) in respect of which headers or metadata
 27.4903 +   items are available, then the following apply:
 27.4904 +
 27.4905 +   o  If the MSGID argument is specified, the results MUST be those
 27.4906 +      available for the first form of the HDR command.
 27.4907 +
 27.4908 +   o  If the RANGE argument is specified, the results MUST be those
 27.4909 +      available for the second and third forms of the HDR command.
 27.4910 +
 27.4911 +   o  If no argument is specified, the results MUST be those available
 27.4912 +      in all forms of the HDR command (that is, it MUST only list those
 27.4913 +      items listed in both the previous cases).
 27.4914 +
 27.4915 +   If the server does not treat the various forms differently, then it
 27.4916 +   MUST ignore any argument and always produce the same results (though
 27.4917 +   not necessarily always in the same order).
 27.4918 +
 27.4919 +   If the HDR command is not implemented, the meaning of the output from
 27.4920 +   this command is not specified, but it must still meet the above
 27.4921 +   syntactic requirements.
 27.4922 +
 27.4923 +
 27.4924 +
 27.4925 +
 27.4926 +
 27.4927 +
 27.4928 +Feather                     Standards Track                    [Page 88]
 27.4929 +
 27.4930 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4931 +
 27.4932 +
 27.4933 +8.6.3.  Examples
 27.4934 +
 27.4935 +   Example of an implementation providing access to only a few headers:
 27.4936 +
 27.4937 +      [C] LIST HEADERS
 27.4938 +      [S] 215 headers supported:
 27.4939 +      [S] Subject
 27.4940 +      [S] Message-ID
 27.4941 +      [S] Xref
 27.4942 +      [S] .
 27.4943 +
 27.4944 +   Example of an implementation providing access to the same fields as
 27.4945 +   the first example in Section 8.4.3:
 27.4946 +
 27.4947 +      [C] CAPABILITIES
 27.4948 +      [S] 101 Capability list:
 27.4949 +      [S] VERSION 2
 27.4950 +      [S] READER
 27.4951 +      [S] OVER
 27.4952 +      [S] HDR
 27.4953 +      [S] LIST ACTIVE NEWSGROUPS HEADERS OVERVIEW.FMT
 27.4954 +      [S] .
 27.4955 +      [C] LIST HEADERS
 27.4956 +      [S] 215 headers and metadata items supported:
 27.4957 +      [S] Date
 27.4958 +      [S] Distribution
 27.4959 +      [S] From
 27.4960 +      [S] Message-ID
 27.4961 +      [S] References
 27.4962 +      [S] Subject
 27.4963 +      [S] Xref
 27.4964 +      [S] :bytes
 27.4965 +      [S] :lines
 27.4966 +      [S] .
 27.4967 +
 27.4968 +   Example of an implementation providing access to all headers:
 27.4969 +
 27.4970 +      [C] LIST HEADERS
 27.4971 +      [S] 215 metadata items supported:
 27.4972 +      [S] :
 27.4973 +      [S] :lines
 27.4974 +      [S] :bytes
 27.4975 +      [S] :x-article-number
 27.4976 +      [S] .
 27.4977 +
 27.4978 +
 27.4979 +
 27.4980 +
 27.4981 +
 27.4982 +
 27.4983 +
 27.4984 +Feather                     Standards Track                    [Page 89]
 27.4985 +
 27.4986 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.4987 +
 27.4988 +
 27.4989 +   Example of an implementation distinguishing the first form of the HDR
 27.4990 +   command from the other two forms:
 27.4991 +
 27.4992 +      [C] LIST HEADERS RANGE
 27.4993 +      [S] 215 metadata items supported:
 27.4994 +      [S] :
 27.4995 +      [S] :lines
 27.4996 +      [S] :bytes
 27.4997 +      [S] .
 27.4998 +      [C] LIST HEADERS MSGID
 27.4999 +      [S] 215 headers and metadata items supported:
 27.5000 +      [S] Date
 27.5001 +      [S] Distribution
 27.5002 +      [S] From
 27.5003 +      [S] Message-ID
 27.5004 +      [S] References
 27.5005 +      [S] Subject
 27.5006 +      [S] :lines
 27.5007 +      [S] :bytes
 27.5008 +      [S] :x-article-number
 27.5009 +      [S] .
 27.5010 +      [C] LIST HEADERS
 27.5011 +      [S] 215 headers and metadata items supported:
 27.5012 +      [S] Date
 27.5013 +      [S] Distribution
 27.5014 +      [S] From
 27.5015 +      [S] Message-ID
 27.5016 +      [S] References
 27.5017 +      [S] Subject
 27.5018 +      [S] :lines
 27.5019 +      [S] :bytes
 27.5020 +      [S] .
 27.5021 +
 27.5022 +   Note that :x-article-number does not appear in the last set of
 27.5023 +   output.
 27.5024 +
 27.5025 +9.  Augmented BNF Syntax for NNTP
 27.5026 +
 27.5027 +9.1.  Introduction
 27.5028 +
 27.5029 +   Each of the following sections describes the syntax of a major
 27.5030 +   element of NNTP.  This syntax extends and refines the descriptions
 27.5031 +   elsewhere in this specification and should be given precedence when
 27.5032 +   resolving apparent conflicts.  Note that ABNF [RFC4234] strings are
 27.5033 +   case insensitive.  Non-terminals used in several places are defined
 27.5034 +   in a separate section at the end.
 27.5035 +
 27.5036 +
 27.5037 +
 27.5038 +
 27.5039 +
 27.5040 +Feather                     Standards Track                    [Page 90]
 27.5041 +
 27.5042 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5043 +
 27.5044 +
 27.5045 +   Between them, the non-terminals <command-line>, <command-datastream>,
 27.5046 +   <command-continuation>, and <response> specify the text that flows
 27.5047 +   between client and server.  A consistent naming scheme is used in
 27.5048 +   this document for the non-terminals relating to each command, and
 27.5049 +   SHOULD be used by the specification of registered extensions.
 27.5050 +
 27.5051 +   For each command, the sequence is as follows:
 27.5052 +
 27.5053 +   o  The client sends an instance of <command-line>; the syntax for the
 27.5054 +      EXAMPLE command is <example-command>.
 27.5055 +
 27.5056 +   o  If the client is one that immediately streams data, it sends an
 27.5057 +      instance of <command-datastream>; the syntax for the EXAMPLE
 27.5058 +      command is <example-datastream>.
 27.5059 +
 27.5060 +   o  The server sends an instance of <response>.
 27.5061 +
 27.5062 +      *  The initial response line is independent of the command that
 27.5063 +         generated it; if the 000 response has arguments, the syntax of
 27.5064 +         the initial line is <response-000-content>.
 27.5065 +
 27.5066 +      *  If the response is multi-line, the initial line is followed by
 27.5067 +         a <multi-line-data-block>.  The syntax for the contents of this
 27.5068 +         block after "dot-stuffing" has been removed is (for the 000
 27.5069 +         response to the EXAMPLE command) <example-000-ml-content> and
 27.5070 +         is an instance of <multi-line-response-content>.
 27.5071 +
 27.5072 +   o  While the latest response is one that indicates more data is
 27.5073 +      required (in general, a 3xx response):
 27.5074 +
 27.5075 +      *  the client sends an instance of <command-continuation>; the
 27.5076 +         syntax for the EXAMPLE continuation following a 333 response is
 27.5077 +         <example-333-continuation>;
 27.5078 +
 27.5079 +      *  the server sends another instance of <response>, as above.
 27.5080 +
 27.5081 +   (There are no commands in this specification that immediately stream
 27.5082 +   data, but this non-terminal is defined for the convenience of
 27.5083 +   extensions.)
 27.5084 +
 27.5085 +
 27.5086 +
 27.5087 +
 27.5088 +
 27.5089 +
 27.5090 +
 27.5091 +
 27.5092 +
 27.5093 +
 27.5094 +
 27.5095 +
 27.5096 +Feather                     Standards Track                    [Page 91]
 27.5097 +
 27.5098 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5099 +
 27.5100 +
 27.5101 +9.2.  Commands
 27.5102 +
 27.5103 +   This syntax defines the non-terminal <command-line>, which represents
 27.5104 +   what is sent from the client to the server (see section 3.1 for
 27.5105 +   limits on lengths).
 27.5106 +
 27.5107 +     command-line = command EOL
 27.5108 +     command = X-command
 27.5109 +     X-command = keyword *(WS token)
 27.5110 +
 27.5111 +     command =/ article-command /
 27.5112 +           body-command /
 27.5113 +           capabilities-command /
 27.5114 +           date-command /
 27.5115 +           group-command /
 27.5116 +           hdr-command /
 27.5117 +           head-command /
 27.5118 +           help-command /
 27.5119 +           ihave-command /
 27.5120 +           last-command /
 27.5121 +           list-command /
 27.5122 +           listgroup-command /
 27.5123 +           mode-reader-command /
 27.5124 +           newgroups-command /
 27.5125 +           newnews-command /
 27.5126 +           next-command /
 27.5127 +           over-command /
 27.5128 +           post-command /
 27.5129 +           quit-command /
 27.5130 +           stat-command
 27.5131 +
 27.5132 +     article-command = "ARTICLE" [WS article-ref]
 27.5133 +     body-command = "BODY" [WS article-ref]
 27.5134 +     capabilities-command = "CAPABILITIES" [WS keyword]
 27.5135 +     date-command = "DATE"
 27.5136 +     group-command = "GROUP" [WS newsgroup-name]
 27.5137 +     hdr-command = "HDR" WS header-meta-name [WS range-ref]
 27.5138 +     head-command = "HEAD" [WS article-ref]
 27.5139 +     help-command = "HELP"
 27.5140 +     ihave-command = "IHAVE" WS message-id
 27.5141 +     last-command = "LAST"
 27.5142 +     list-command = "LIST" [WS list-arguments]
 27.5143 +     listgroup-command = "LISTGROUP" [WS newsgroup-name [WS range]]
 27.5144 +     mode-reader-command = "MODE" WS "READER"
 27.5145 +     newgroups-command = "NEWGROUPS" WS date-time
 27.5146 +     newnews-command = "NEWNEWS" WS wildmat WS date-time
 27.5147 +     next-command = "NEXT"
 27.5148 +     over-command = "OVER" [WS range-ref]
 27.5149 +
 27.5150 +
 27.5151 +
 27.5152 +Feather                     Standards Track                    [Page 92]
 27.5153 +
 27.5154 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5155 +
 27.5156 +
 27.5157 +     post-command = "POST"
 27.5158 +     quit-command = "QUIT"
 27.5159 +     stat-command = "STAT" [WS article-ref]
 27.5160 +
 27.5161 +     article-ref = article-number / message-id
 27.5162 +     date = date2y / date4y
 27.5163 +     date4y = 4DIGIT 2DIGIT 2DIGIT
 27.5164 +     date2y = 2DIGIT 2DIGIT 2DIGIT
 27.5165 +     date-time = date WS time [WS "GMT"]
 27.5166 +     header-meta-name = header-name / metadata-name
 27.5167 +     list-arguments = keyword [WS token]
 27.5168 +     metadata-name = ":" 1*A-NOTCOLON
 27.5169 +     range = article-number ["-" [article-number]]
 27.5170 +     range-ref = range / message-id
 27.5171 +     time = 2DIGIT 2DIGIT 2DIGIT
 27.5172 +
 27.5173 +9.3.  Command Continuation
 27.5174 +
 27.5175 +   This syntax defines the further material sent by the client in the
 27.5176 +   case of multi-stage commands and those that stream data.
 27.5177 +
 27.5178 +     command-datastream = UNDEFINED
 27.5179 +       ; not used, provided as a hook for extensions
 27.5180 +     command-continuation = ihave-335-continuation /
 27.5181 +           post-340-continuation
 27.5182 +
 27.5183 +     ihave-335-continuation = encoded-article
 27.5184 +     post-340-continuation = encoded-article
 27.5185 +
 27.5186 +     encoded-article = multi-line-data-block
 27.5187 +       ; after undoing the "dot-stuffing", this MUST match <article>
 27.5188 +
 27.5189 +9.4.  Responses
 27.5190 +
 27.5191 +9.4.1.  Generic Responses
 27.5192 +
 27.5193 +   This syntax defines the non-terminal <response>, which represents the
 27.5194 +   generic form of responses; that is, what is sent from the server to
 27.5195 +   the client in response to a <command> or a <command-continuation>.
 27.5196 +
 27.5197 +     response = simple-response / multi-line-response
 27.5198 +     simple-response = initial-response-line
 27.5199 +     multi-line-response = initial-response-line multi-line-data-block
 27.5200 +
 27.5201 +     initial-response-line =
 27.5202 +           initial-response-content [SP trailing-comment] CRLF
 27.5203 +     initial-response-content = X-initial-response-content
 27.5204 +     X-initial-response-content = 3DIGIT *(SP response-argument)
 27.5205 +
 27.5206 +
 27.5207 +
 27.5208 +Feather                     Standards Track                    [Page 93]
 27.5209 +
 27.5210 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5211 +
 27.5212 +
 27.5213 +     response-argument = 1*A-CHAR
 27.5214 +     trailing-comment = *U-CHAR
 27.5215 +
 27.5216 +9.4.2.  Initial Response Line Contents
 27.5217 +
 27.5218 +   This syntax defines the specific initial response lines for the
 27.5219 +   various commands in this specification (see section 3.1 for limits on
 27.5220 +   lengths).  Only those response codes with arguments are listed.
 27.5221 +
 27.5222 +     initial-response-content =/ response-111-content /
 27.5223 +           response-211-content /
 27.5224 +           response-220-content /
 27.5225 +           response-221-content /
 27.5226 +           response-222-content /
 27.5227 +           response-223-content /
 27.5228 +           response-401-content
 27.5229 +
 27.5230 +     response-111-content = "111" SP date4y time
 27.5231 +     response-211-content = "211" 3(SP article-number) SP newsgroup-name
 27.5232 +     response-220-content = "220" SP article-number SP message-id
 27.5233 +     response-221-content = "221" SP article-number SP message-id
 27.5234 +     response-222-content = "222" SP article-number SP message-id
 27.5235 +     response-223-content = "223" SP article-number SP message-id
 27.5236 +     response-401-content = "401" SP capability-label
 27.5237 +
 27.5238 +9.4.3.  Multi-line Response Contents
 27.5239 +
 27.5240 +   This syntax defines the content of the various multi-line responses;
 27.5241 +   more precisely, it defines the part of the response in the multi-line
 27.5242 +   data block after any "dot-stuffing" has been undone.  The numeric
 27.5243 +   portion of each non-terminal name indicates the response code that is
 27.5244 +   followed by this data.
 27.5245 +
 27.5246 +     multi-line-response-content = article-220-ml-content /
 27.5247 +           body-222-ml-content /
 27.5248 +           capabilities-101-ml-content /
 27.5249 +           hdr-225-ml-content /
 27.5250 +           head-221-ml-content /
 27.5251 +           help-100-ml-content /
 27.5252 +           list-215-ml-content /
 27.5253 +           listgroup-211-ml-content /
 27.5254 +           newgroups-231-ml-content /
 27.5255 +           newnews-230-ml-content /
 27.5256 +           over-224-ml-content
 27.5257 +
 27.5258 +     article-220-ml-content = article
 27.5259 +     body-222-ml-content = body
 27.5260 +     capabilities-101-ml-content = version-line CRLF
 27.5261 +
 27.5262 +
 27.5263 +
 27.5264 +Feather                     Standards Track                    [Page 94]
 27.5265 +
 27.5266 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5267 +
 27.5268 +
 27.5269 +           *(capability-line CRLF)
 27.5270 +     hdr-225-ml-content = *(article-number SP hdr-content CRLF)
 27.5271 +     head-221-ml-content = 1*header
 27.5272 +     help-100-ml-content = *(*U-CHAR CRLF)
 27.5273 +     list-215-ml-content = list-content
 27.5274 +     listgroup-211-ml-content = *(article-number CRLF)
 27.5275 +     newgroups-231-ml-content = active-groups-list
 27.5276 +     newnews-230-ml-content = *(message-id CRLF)
 27.5277 +     over-224-ml-content = *(article-number over-content CRLF)
 27.5278 +
 27.5279 +     active-groups-list = *(newsgroup-name SPA article-number
 27.5280 +           SPA article-number SPA newsgroup-status CRLF)
 27.5281 +     hdr-content = *S-NONTAB
 27.5282 +     hdr-n-content = [(header-name ":" / metadata-name) SP hdr-content]
 27.5283 +     list-content = body
 27.5284 +     newsgroup-status = %x79 / %x6E / %x6D / private-status
 27.5285 +     over-content = 1*6(TAB hdr-content) /
 27.5286 +           7(TAB hdr-content) *(TAB hdr-n-content)
 27.5287 +     private-status = token ; except the values in newsgroup-status
 27.5288 +
 27.5289 +9.5.  Capability Lines
 27.5290 +
 27.5291 +   This syntax defines the generic form of a capability line in the
 27.5292 +   capabilities list (see Section 3.3.1).
 27.5293 +
 27.5294 +     capability-line = capability-entry
 27.5295 +     capability-entry = X-capability-entry
 27.5296 +     X-capability-entry = capability-label *(WS capability-argument)
 27.5297 +     capability-label = keyword
 27.5298 +     capability-argument = token
 27.5299 +
 27.5300 +   This syntax defines the specific capability entries for the
 27.5301 +   capabilities in this specification.
 27.5302 +
 27.5303 +     capability-entry =/
 27.5304 +           hdr-capability /
 27.5305 +           ihave-capability /
 27.5306 +           implementation-capability /
 27.5307 +           list-capability /
 27.5308 +           mode-reader-capability /
 27.5309 +           newnews-capability /
 27.5310 +           over-capability /
 27.5311 +           post-capability /
 27.5312 +           reader-capability
 27.5313 +
 27.5314 +     hdr-capability = "HDR"
 27.5315 +     ihave-capability = "IHAVE"
 27.5316 +     implementation-capability = "IMPLEMENTATION" *(WS token)
 27.5317 +
 27.5318 +
 27.5319 +
 27.5320 +Feather                     Standards Track                    [Page 95]
 27.5321 +
 27.5322 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5323 +
 27.5324 +
 27.5325 +     list-capability = "LIST" 1*(WS keyword)
 27.5326 +     mode-reader-capability = "MODE-READER"
 27.5327 +     newnews-capability = "NEWNEWS"
 27.5328 +     over-capability = "OVER" [WS "MSGID"]
 27.5329 +     post-capability = "POST"
 27.5330 +     reader-capability = "READER"
 27.5331 +
 27.5332 +     version-line = "VERSION" 1*(WS version-number)
 27.5333 +     version-number = nzDIGIT *5DIGIT
 27.5334 +
 27.5335 +9.6.  LIST Variants
 27.5336 +
 27.5337 +   This section defines more specifically the keywords for the LIST
 27.5338 +   command and the syntax of the corresponding response contents.
 27.5339 +
 27.5340 +     ; active
 27.5341 +     list-arguments =/ "ACTIVE" [WS wildmat]
 27.5342 +     list-content =/ list-active-content
 27.5343 +     list-active-content = active-groups-list
 27.5344 +
 27.5345 +
 27.5346 +     ; active.times
 27.5347 +     list-arguments =/ "ACTIVE.TIMES" [WS wildmat]
 27.5348 +     list-content =/ list-active-times-content
 27.5349 +     list-active-times-content =
 27.5350 +           *(newsgroup-name SPA 1*DIGIT SPA newsgroup-creator CRLF)
 27.5351 +     newsgroup-creator = U-TEXT
 27.5352 +
 27.5353 +
 27.5354 +     ; distrib.pats
 27.5355 +     list-arguments =/ "DISTRIB.PATS"
 27.5356 +     list-content =/ list-distrib-pats-content
 27.5357 +     list-distrib-pats-content =
 27.5358 +           *(1*DIGIT ":" wildmat ":" distribution CRLF)
 27.5359 +     distribution = token
 27.5360 +
 27.5361 +
 27.5362 +     ; headers
 27.5363 +     list-arguments =/ "HEADERS" [WS ("MSGID" / "RANGE")]
 27.5364 +     list-content =/ list-headers-content
 27.5365 +     list-headers-content = *(header-meta-name CRLF) /
 27.5366 +           *((metadata-name / ":") CRLF)
 27.5367 +
 27.5368 +
 27.5369 +     ; newsgroups
 27.5370 +     list-arguments =/ "NEWSGROUPS" [WS wildmat]
 27.5371 +     list-content =/ list-newsgroups-content
 27.5372 +     list-newsgroups-content =
 27.5373 +
 27.5374 +
 27.5375 +
 27.5376 +Feather                     Standards Track                    [Page 96]
 27.5377 +
 27.5378 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5379 +
 27.5380 +
 27.5381 +           *(newsgroup-name WS newsgroup-description CRLF)
 27.5382 +     newsgroup-description = S-TEXT
 27.5383 +
 27.5384 +
 27.5385 +     ; overview.fmt
 27.5386 +     list-arguments =/ "OVERVIEW.FMT"
 27.5387 +     list-content =/ list-overview-fmt-content
 27.5388 +     list-overview-fmt-content = "Subject:" CRLF
 27.5389 +           "From:" CRLF
 27.5390 +           "Date:" CRLF
 27.5391 +           "Message-ID:" CRLF
 27.5392 +           "References:" CRLF
 27.5393 +           ( ":bytes" CRLF ":lines" / "Bytes:" CRLF "Lines:") CRLF
 27.5394 +           *((header-name ":full" / metadata-name) CRLF)
 27.5395 +
 27.5396 +9.7.  Articles
 27.5397 +
 27.5398 +   This syntax defines the non-terminal <article>, which represents the
 27.5399 +   format of an article as described in Section 3.6.
 27.5400 +
 27.5401 +     article = 1*header CRLF body
 27.5402 +     header = header-name ":" [CRLF] SP header-content CRLF
 27.5403 +     header-content = *(S-CHAR / [CRLF] WS)
 27.5404 +     body = *(*B-CHAR CRLF)
 27.5405 +
 27.5406 +9.8.  General Non-terminals
 27.5407 +
 27.5408 +   These non-terminals are used at various places in the syntax and are
 27.5409 +   collected here for convenience.  A few of these non-terminals are not
 27.5410 +   used in this specification but are provided for the consistency and
 27.5411 +   convenience of extension authors.
 27.5412 +
 27.5413 +     multi-line-data-block = content-lines termination
 27.5414 +     content-lines = *([content-text] CRLF)
 27.5415 +     content-text = (".." / B-NONDOT) *B-CHAR
 27.5416 +     termination = "." CRLF
 27.5417 +
 27.5418 +     article-number = 1*16DIGIT
 27.5419 +     header-name = 1*A-NOTCOLON
 27.5420 +     keyword = ALPHA 2*(ALPHA / DIGIT / "." / "-")
 27.5421 +     message-id = "<" 1*248A-NOTGT ">"
 27.5422 +     newsgroup-name = 1*wildmat-exact
 27.5423 +     token = 1*P-CHAR
 27.5424 +
 27.5425 +     wildmat = wildmat-pattern *("," ["!"] wildmat-pattern)
 27.5426 +     wildmat-pattern = 1*wildmat-item
 27.5427 +     wildmat-item = wildmat-exact / wildmat-wild
 27.5428 +     wildmat-exact = %x22-29 / %x2B / %x2D-3E / %x40-5A / %x5E-7E /
 27.5429 +
 27.5430 +
 27.5431 +
 27.5432 +Feather                     Standards Track                    [Page 97]
 27.5433 +
 27.5434 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5435 +
 27.5436 +
 27.5437 +          UTF8-non-ascii  ; exclude ! * , ? [ \ ]
 27.5438 +     wildmat-wild = "*" / "?"
 27.5439 +
 27.5440 +     base64 = *(4base64-char) [base64-terminal]
 27.5441 +     base64-char = UPPER / LOWER / DIGIT / "+" / "/"
 27.5442 +     base64-terminal = 2base64-char "==" / 3base64-char "="
 27.5443 +
 27.5444 +     ; Assorted special character sets
 27.5445 +     ;   A- means based on US-ASCII, excluding controls and SP
 27.5446 +     ;   P- means based on UTF-8, excluding controls and SP
 27.5447 +     ;   U- means based on UTF-8, excluding NUL CR and LF
 27.5448 +     ;   B- means based on bytes, excluding NUL CR and LF
 27.5449 +     A-CHAR     = %x21-7E
 27.5450 +     A-NOTCOLON = %x21-39 / %x3B-7E  ; exclude ":"
 27.5451 +     A-NOTGT    = %x21-3D / %x3F-7E  ; exclude ">"
 27.5452 +     P-CHAR     = A-CHAR / UTF8-non-ascii
 27.5453 +     U-CHAR     = CTRL / TAB / SP / A-CHAR / UTF8-non-ascii
 27.5454 +     U-NONTAB   = CTRL /       SP / A-CHAR / UTF8-non-ascii
 27.5455 +     U-TEXT     = P-CHAR *U-CHAR
 27.5456 +     B-CHAR     = CTRL / TAB / SP / %x21-FF
 27.5457 +     B-NONDOT   = CTRL / TAB / SP / %x21-2D / %x2F-FF  ; exclude "."
 27.5458 +
 27.5459 +     ALPHA = UPPER / LOWER   ; use only when case-insensitive
 27.5460 +     CR = %x0D
 27.5461 +     CRLF = CR LF
 27.5462 +     CTRL = %x01-08 / %x0B-0C / %x0E-1F
 27.5463 +     DIGIT = %x30-39
 27.5464 +     nzDIGIT = %x31-39
 27.5465 +     EOL = *(SP / TAB) CRLF
 27.5466 +     LF = %x0A
 27.5467 +     LOWER = %x61-7A
 27.5468 +     SP = %x20
 27.5469 +     SPA = 1*SP
 27.5470 +     TAB = %x09
 27.5471 +     UPPER = %x41-5A
 27.5472 +     UTF8-non-ascii = UTF8-2 / UTF8-3 / UTF8-4
 27.5473 +     UTF8-2    = %xC2-DF UTF8-tail
 27.5474 +     UTF8-3    = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2UTF8-tail /
 27.5475 +                 %xED %x80-9F UTF8-tail / %xEE-EF 2UTF8-tail
 27.5476 +     UTF8-4    = %xF0 %x90-BF 2UTF8-tail / %xF1-F3 3UTF8-tail /
 27.5477 +                 %xF4 %x80-8F 2UTF8-tail
 27.5478 +     UTF8-tail = %x80-BF
 27.5479 +     WS = 1*(SP / TAB)
 27.5480 +
 27.5481 +   The following non-terminals require special consideration.  They
 27.5482 +   represent situations where material SHOULD be restricted to UTF-8,
 27.5483 +   but implementations MUST be able to cope with other character
 27.5484 +   encodings.  Therefore, there are two sets of definitions for them.
 27.5485 +
 27.5486 +
 27.5487 +
 27.5488 +Feather                     Standards Track                    [Page 98]
 27.5489 +
 27.5490 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5491 +
 27.5492 +
 27.5493 +   Implementations MUST accept any content that meets this syntax:
 27.5494 +
 27.5495 +     S-CHAR   = %x21-FF
 27.5496 +     S-NONTAB = CTRL / SP / S-CHAR
 27.5497 +     S-TEXT   = (CTRL / S-CHAR) *B-CHAR
 27.5498 +
 27.5499 +   and MAY pass such content on unaltered.
 27.5500 +
 27.5501 +   When generating new content or re-encoding existing content,
 27.5502 +   implementations SHOULD conform to this syntax:
 27.5503 +
 27.5504 +     S-CHAR   = P-CHAR
 27.5505 +     S-NONTAB = U-NONTAB
 27.5506 +     S-TEXT   = U-TEXT
 27.5507 +
 27.5508 +9.9.  Extensions and Validation
 27.5509 +
 27.5510 +   The specification of a registered extension MUST include formal
 27.5511 +   syntax that defines additional forms for the following non-terminals:
 27.5512 +
 27.5513 +   command
 27.5514 +      for each new command other than a variant of the LIST command -
 27.5515 +      the syntax of each command MUST be compatible with the definition
 27.5516 +      of <X-command>;
 27.5517 +
 27.5518 +   command-datastream
 27.5519 +      for each new command that immediately streams data;
 27.5520 +
 27.5521 +   command-continuation
 27.5522 +      for each new command that sends further material after the initial
 27.5523 +      command line - the syntax of each continuation MUST be exactly
 27.5524 +      what is sent to the server, including any escape mechanisms such
 27.5525 +      as "dot-stuffing";
 27.5526 +
 27.5527 +   initial-response-content
 27.5528 +      for each new response code that has arguments - the syntax of each
 27.5529 +      response MUST be compatible with the definition of <X-initial-
 27.5530 +      response-content>;
 27.5531 +
 27.5532 +   multi-line-response-content
 27.5533 +      for each new response code that has a multi-line response - the
 27.5534 +      syntax MUST show the response after the lines containing the
 27.5535 +      response code and the terminating octet have been removed and any
 27.5536 +      "dot-stuffing" undone;
 27.5537 +
 27.5538 +   capability-entry
 27.5539 +      for each new capability label - the syntax of each entry MUST be
 27.5540 +      compatible with the definition of <X-capability-entry>;
 27.5541 +
 27.5542 +
 27.5543 +
 27.5544 +Feather                     Standards Track                    [Page 99]
 27.5545 +
 27.5546 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5547 +
 27.5548 +
 27.5549 +   list-arguments
 27.5550 +      for each new variant of the LIST command - the syntax of each
 27.5551 +      entry MUST be compatible with the definition of <X-command>;
 27.5552 +
 27.5553 +   list-content
 27.5554 +      for each new variant of the LIST command - the syntax MUST show
 27.5555 +      the response after the lines containing the 215 response code and
 27.5556 +      the terminating octet have been removed and any "dot-stuffing"
 27.5557 +      undone.
 27.5558 +
 27.5559 +   The =/ notation of ABNF [RFC4234] and the naming conventions
 27.5560 +   described in Section 9.1 SHOULD be used for this.
 27.5561 +
 27.5562 +   When the syntax in this specification, or syntax based on it, is
 27.5563 +   validated, it should be noted that:
 27.5564 +
 27.5565 +   o  the non-terminals <command-line>, <command-datastream>,
 27.5566 +      <command-continuation>, <response>, and
 27.5567 +      <multi-line-response-content> describe basic concepts of the
 27.5568 +      protocol and are not referred to by any other rule;
 27.5569 +
 27.5570 +   o  the non-terminal <base64> is provided for the convenience of
 27.5571 +      extension authors and is not referred to by any rule in this
 27.5572 +      specification;
 27.5573 +
 27.5574 +   o  for the reasons given above, the non-terminals <S-CHAR>,
 27.5575 +      <S-NONTAB>, and <S-TEXT> each have two definitions; and
 27.5576 +
 27.5577 +   o  the non-terminal <UNDEFINED> is deliberately not defined.
 27.5578 +
 27.5579 +10.  Internationalisation Considerations
 27.5580 +
 27.5581 +10.1.  Introduction and Historical Situation
 27.5582 +
 27.5583 +   RFC 977 [RFC977] was written at a time when internationalisation was
 27.5584 +   not seen as a significant issue.  As such, it was written on the
 27.5585 +   assumption that all communication would be in ASCII and use only a
 27.5586 +   7-bit transport layer, although in practice just about all known
 27.5587 +   implementations are 8-bit clean.
 27.5588 +
 27.5589 +   Since then, Usenet and NNTP have spread throughout the world.  In the
 27.5590 +   absence of standards for handling the issues of language and
 27.5591 +   character sets, countries, newsgroup hierarchies, and individuals
 27.5592 +   have found a variety of solutions that work for them but that are not
 27.5593 +   necessarily appropriate elsewhere.  For example, some have adopted a
 27.5594 +   default 8-bit character set appropriate to their needs (such as
 27.5595 +   ISO/IEC 8859-1 in Western Europe or KOI-8 in Russia), others have
 27.5596 +   used ASCII (either US-ASCII or national variants) in headers but
 27.5597 +
 27.5598 +
 27.5599 +
 27.5600 +Feather                     Standards Track                   [Page 100]
 27.5601 +
 27.5602 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5603 +
 27.5604 +
 27.5605 +   local 16-bit character sets in article bodies, and still others have
 27.5606 +   gone for a combination of MIME [RFC2045] and UTF-8.  With the
 27.5607 +   increased use of MIME in email, it is becoming more common to find
 27.5608 +   NNTP articles containing MIME headers that identify the character set
 27.5609 +   of the body, but this is far from universal.
 27.5610 +
 27.5611 +   The resulting confusion does not help interoperability.
 27.5612 +
 27.5613 +   One point that has been generally accepted is that articles can
 27.5614 +   contain octets with the top bit set, and NNTP is only expected to
 27.5615 +   operate on 8-bit clean transport paths.
 27.5616 +
 27.5617 +10.2.  This Specification
 27.5618 +
 27.5619 +   Part of the role of this present specification is to eliminate this
 27.5620 +   confusion and promote interoperability as far as possible.  At the
 27.5621 +   same time, it is necessary to accept the existence of the present
 27.5622 +   situation and not break existing implementations and arrangements
 27.5623 +   gratuitously, even if they are less than optimal.  Therefore, the
 27.5624 +   current practice described above has been taken into consideration in
 27.5625 +   producing this specification.
 27.5626 +
 27.5627 +   This specification extends NNTP from US-ASCII [ANSI1986] to UTF-8
 27.5628 +   [RFC3629].  Except in the two areas discussed below, UTF-8 (which is
 27.5629 +   a superset of US-ASCII) is mandatory, and implementations MUST NOT
 27.5630 +   use any other encoding.
 27.5631 +
 27.5632 +   Firstly, the use of MIME for article headers and bodies is strongly
 27.5633 +   recommended.  However, given widely divergent existing practices, an
 27.5634 +   attempt to require a particular encoding and tagging standard would
 27.5635 +   be premature at this time.  Accordingly, this specification allows
 27.5636 +   the use of arbitrary 8-bit data in articles subject to the following
 27.5637 +   requirements and recommendations.
 27.5638 +
 27.5639 +   o  The names of headers (e.g., "From" or "Subject") MUST be in
 27.5640 +      US-ASCII.
 27.5641 +
 27.5642 +   o  Header values SHOULD use US-ASCII or an encoding based on it, such
 27.5643 +      as RFC 2047 [RFC2047], until such time as another approach has
 27.5644 +      been standardised.  At present, 8-bit encodings (including UTF-8)
 27.5645 +      SHOULD NOT be used because they are likely to cause
 27.5646 +      interoperability problems.
 27.5647 +
 27.5648 +   o  The character set of article bodies SHOULD be indicated in the
 27.5649 +      article headers, and this SHOULD be done in accordance with MIME.
 27.5650 +
 27.5651 +   o  Where an article is obtained from an external source, an
 27.5652 +      implementation MAY pass it on and derive data from it (such as the
 27.5653 +
 27.5654 +
 27.5655 +
 27.5656 +Feather                     Standards Track                   [Page 101]
 27.5657 +
 27.5658 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5659 +
 27.5660 +
 27.5661 +      response to the HDR command), even though the article or the data
 27.5662 +      does not meet the above requirements.  Implementations MUST
 27.5663 +      transfer such articles and data correctly and unchanged; they MUST
 27.5664 +      NOT attempt to convert or re-encode the article or derived data.
 27.5665 +      (Nevertheless, a client or server MAY elect not to post or forward
 27.5666 +      the article if, after further examination of the article, it deems
 27.5667 +      it inappropriate to do so.)
 27.5668 +
 27.5669 +   This requirement affects the ARTICLE (Section 6.2.1), BODY
 27.5670 +   (Section 6.2.3), HDR (Section 8.5), HEAD (Section 6.2.2), IHAVE
 27.5671 +   (Section 6.3.2), OVER (Section 8.3), and POST (Section 6.3.1)
 27.5672 +   commands.
 27.5673 +
 27.5674 +   Secondly, the following requirements are placed on the newsgroups
 27.5675 +   list returned by the LIST NEWSGROUPS command (Section 7.6.6):
 27.5676 +
 27.5677 +   o  Although this specification allows UTF-8 for newsgroup names, they
 27.5678 +      SHOULD be restricted to US-ASCII until a successor to RFC 1036
 27.5679 +      [RFC1036] standardises another approach. 8-bit encodings SHOULD
 27.5680 +      NOT be used because they are likely to cause interoperability
 27.5681 +      problems.
 27.5682 +
 27.5683 +   o  The newsgroup description SHOULD be in US-ASCII or UTF-8 unless
 27.5684 +      and until a successor to RFC 1036 standardises other encoding
 27.5685 +      arrangements.  8-bit encodings other than UTF-8 SHOULD NOT be used
 27.5686 +      because they are likely to cause interoperability problems.
 27.5687 +
 27.5688 +   o  Implementations that obtain this data from an external source MUST
 27.5689 +      handle it correctly even if it does not meet the above
 27.5690 +      requirements.  Implementations (in particular, clients) MUST
 27.5691 +      handle such data correctly.
 27.5692 +
 27.5693 +10.3.  Outstanding Issues
 27.5694 +
 27.5695 +   While the primary use of NNTP is for transmitting articles that
 27.5696 +   conform to RFC 1036 (Netnews articles), it is also used for other
 27.5697 +   formats (see Appendix A).  It is therefore most appropriate that
 27.5698 +   internationalisation issues related to article formats be addressed
 27.5699 +   in the relevant specifications.  For Netnews articles, this is any
 27.5700 +   successor to RFC 1036.  For email messages, it is RFC 2822 [RFC2822].
 27.5701 +
 27.5702 +   Of course, any article transmitted via NNTP needs to conform to this
 27.5703 +   specification as well.
 27.5704 +
 27.5705 +   Restricting newsgroup names to UTF-8 is not a complete solution.  In
 27.5706 +   particular, when new newsgroup names are created or a user is asked
 27.5707 +   to enter a newsgroup name, some scheme of canonicalisation will need
 27.5708 +   to take place.  This specification does not attempt to define that
 27.5709 +
 27.5710 +
 27.5711 +
 27.5712 +Feather                     Standards Track                   [Page 102]
 27.5713 +
 27.5714 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5715 +
 27.5716 +
 27.5717 +   canonicalization; further work is needed in this area, in conjunction
 27.5718 +   with the article format specifications.  Until such specifications
 27.5719 +   are published, implementations SHOULD match newsgroup names octet by
 27.5720 +   octet.  It is anticipated that any approved scheme will be applied
 27.5721 +   "at the edges", and therefore octet-by-octet comparison will continue
 27.5722 +   to apply to most, if not all, uses of newsgroup names in NNTP.
 27.5723 +
 27.5724 +   In the meantime, any implementation experimenting with UTF-8
 27.5725 +   newsgroup names is strongly cautioned that a future specification may
 27.5726 +   require that those names be canonicalized when used with NNTP in a
 27.5727 +   way that is not compatible with their experiments.
 27.5728 +
 27.5729 +   Since the primary use of NNTP is with Netnews, and since newsgroup
 27.5730 +   descriptions are normally distributed through specially formatted
 27.5731 +   articles, it is recommended that the internationalisation issues
 27.5732 +   related to them be addressed in any successor to RFC 1036.
 27.5733 +
 27.5734 +11.  IANA Considerations
 27.5735 +
 27.5736 +   This specification requires IANA to keep a registry of capability
 27.5737 +   labels.  The initial contents of this registry are specified in
 27.5738 +   Section 3.3.4.  As described in Section 3.3.3, labels beginning with
 27.5739 +   X are reserved for private use, while all other names are expected to
 27.5740 +   be associated with a specification in an RFC on the standards track
 27.5741 +   or defining an IESG-approved experimental protocol.
 27.5742 +
 27.5743 +   Different entries in the registry MUST use different capability
 27.5744 +   labels.
 27.5745 +
 27.5746 +   Different entries in the registry MUST NOT use the same command name.
 27.5747 +   For this purpose, variants distinguished by a second or subsequent
 27.5748 +   keyword (e.g., "LIST HEADERS" and "LIST OVERVIEW.FMT") count as
 27.5749 +   different commands.  If there is a need for two extensions to use the
 27.5750 +   same command, a single harmonised specification MUST be registered.
 27.5751 +
 27.5752 +12.  Security Considerations
 27.5753 +
 27.5754 +   This section is meant to inform application developers, information
 27.5755 +   providers, and users of the security limitations in NNTP as described
 27.5756 +   by this document.  The discussion does not include definitive
 27.5757 +   solutions to the problems revealed, though it does make some
 27.5758 +   suggestions for reducing security risks.
 27.5759 +
 27.5760 +
 27.5761 +
 27.5762 +
 27.5763 +
 27.5764 +
 27.5765 +
 27.5766 +
 27.5767 +
 27.5768 +Feather                     Standards Track                   [Page 103]
 27.5769 +
 27.5770 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5771 +
 27.5772 +
 27.5773 +12.1.  Personal and Proprietary Information
 27.5774 +
 27.5775 +   NNTP, because it was created to distribute network news articles,
 27.5776 +   will forward whatever information is stored in those articles.
 27.5777 +   Specification of that information is outside this scope of this
 27.5778 +   document, but it is likely that some personal and/or proprietary
 27.5779 +   information is available in some of those articles.  It is very
 27.5780 +   important that designers and implementers provide informative
 27.5781 +   warnings to users so that personal and/or proprietary information in
 27.5782 +   material that is added automatically to articles (e.g., in headers)
 27.5783 +   is not disclosed inadvertently.  Additionally, effective and easily
 27.5784 +   understood mechanisms to manage the distribution of news articles
 27.5785 +   SHOULD be provided to NNTP Server administrators, so that they are
 27.5786 +   able to report with confidence the likely spread of any particular
 27.5787 +   set of news articles.
 27.5788 +
 27.5789 +12.2.  Abuse of Server Log Information
 27.5790 +
 27.5791 +   A server is in the position to save session data about a user's
 27.5792 +   requests that might identify their reading patterns or subjects of
 27.5793 +   interest.  This information is clearly confidential in nature, and
 27.5794 +   its handling can be constrained by law in certain countries.  People
 27.5795 +   using this protocol to provide data are responsible for ensuring that
 27.5796 +   such material is not distributed without the permission of any
 27.5797 +   individuals that are identifiable by the published results.
 27.5798 +
 27.5799 +12.3.  Weak Authentication and Access Control
 27.5800 +
 27.5801 +   There is no user-based or token-based authentication in the basic
 27.5802 +   NNTP specification.  Access is normally controlled by server
 27.5803 +   configuration files.  Those files specify access by using domain
 27.5804 +   names or IP addresses.  However, this specification does permit the
 27.5805 +   creation of extensions to NNTP for such purposes; one such extension
 27.5806 +   is [NNTP-AUTH].  While including such mechanisms is optional, doing
 27.5807 +   so is strongly encouraged.
 27.5808 +
 27.5809 +   Other mechanisms are also available.  For example, a proxy server
 27.5810 +   could be put in place that requires authentication before connecting
 27.5811 +   via the proxy to the NNTP server.
 27.5812 +
 27.5813 +12.4.  DNS Spoofing
 27.5814 +
 27.5815 +   Many existing NNTP implementations authorize incoming connections by
 27.5816 +   checking the IP address of that connection against the IP addresses
 27.5817 +   obtained via DNS lookups of lists of domain names given in local
 27.5818 +   configuration files.  Servers that use this type of authentication
 27.5819 +   and clients that find a server by doing a DNS lookup of the server
 27.5820 +   name rely very heavily on the Domain Name Service, and are thus
 27.5821 +
 27.5822 +
 27.5823 +
 27.5824 +Feather                     Standards Track                   [Page 104]
 27.5825 +
 27.5826 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5827 +
 27.5828 +
 27.5829 +   generally prone to security attacks based on the deliberate
 27.5830 +   misassociation of IP addresses and DNS names.  Clients and servers
 27.5831 +   need to be cautious in assuming the continuing validity of an IP
 27.5832 +   number/DNS name association.
 27.5833 +
 27.5834 +   In particular, NNTP clients and servers SHOULD rely on their name
 27.5835 +   resolver for confirmation of an IP number/DNS name association,
 27.5836 +   rather than cache the result of previous host name lookups.  Many
 27.5837 +   platforms already can cache host name lookups locally when
 27.5838 +   appropriate, and they SHOULD be configured to do so.  It is proper
 27.5839 +   for these lookups to be cached, however, only when the TTL (Time To
 27.5840 +   Live) information reported by the name server makes it likely that
 27.5841 +   the cached information will remain useful.
 27.5842 +
 27.5843 +   If NNTP clients or servers cache the results of host name lookups in
 27.5844 +   order to achieve a performance improvement, they MUST observe the TTL
 27.5845 +   information reported by DNS.  If NNTP clients or servers do not
 27.5846 +   observe this rule, they could be spoofed when a previously accessed
 27.5847 +   server's IP address changes.  As network renumbering is expected to
 27.5848 +   become increasingly common, the possibility of this form of attack
 27.5849 +   will increase.  Observing this requirement thus reduces this
 27.5850 +   potential security vulnerability.
 27.5851 +
 27.5852 +   This requirement also improves the load-balancing behaviour of
 27.5853 +   clients for replicated servers using the same DNS name and reduces
 27.5854 +   the likelihood of a user's experiencing failure in accessing sites
 27.5855 +   that use that strategy.
 27.5856 +
 27.5857 +12.5.  UTF-8 Issues
 27.5858 +
 27.5859 +   UTF-8 [RFC3629] permits only certain sequences of octets and
 27.5860 +   designates others as either malformed or "illegal".  The Unicode
 27.5861 +   standard identifies a number of security issues related to illegal
 27.5862 +   sequences and forbids their generation by conforming implementations.
 27.5863 +
 27.5864 +   Implementations of this specification MUST NOT generate malformed or
 27.5865 +   illegal sequences and SHOULD detect them and take some appropriate
 27.5866 +   action.  This could include the following:
 27.5867 +
 27.5868 +   o  Generating a 501 response code.
 27.5869 +
 27.5870 +   o  Replacing such sequences by the sequence %xEF.BF.BD, which encodes
 27.5871 +      the "replacement character" U+FFFD.
 27.5872 +
 27.5873 +   o  Closing the connection.
 27.5874 +
 27.5875 +   o  Replacing such sequences by a "guessed" valid sequence (based on
 27.5876 +      properties of the UTF-8 encoding).
 27.5877 +
 27.5878 +
 27.5879 +
 27.5880 +Feather                     Standards Track                   [Page 105]
 27.5881 +
 27.5882 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5883 +
 27.5884 +
 27.5885 +   In the last case, the implementation MUST ensure that any replacement
 27.5886 +   cannot be used to bypass validity or security checks.  For example,
 27.5887 +   the illegal sequence %xC0.A0 is an over-long encoding for space
 27.5888 +   (%x20).  If it is replaced by the correct encoding in a command line,
 27.5889 +   this needs to happen before the command line is parsed into
 27.5890 +   individual arguments.  If the replacement came after parsing, it
 27.5891 +   would be possible to generate an argument with an embedded space,
 27.5892 +   which is forbidden.  Use of the "replacement character" does not have
 27.5893 +   this problem, since it is permitted wherever non-US-ASCII characters
 27.5894 +   are.  Implementations SHOULD use one of the first two solutions where
 27.5895 +   the general structure of the NNTP stream remains intact and SHOULD
 27.5896 +   close the connection if it is no longer possible to parse it
 27.5897 +   sensibly.
 27.5898 +
 27.5899 +12.6.  Caching of Capability Lists
 27.5900 +
 27.5901 +   The CAPABILITIES command provides a capability list, which is
 27.5902 +   information about the current capabilities of the server.  Whenever
 27.5903 +   there is a relevant change to the server state, the results of this
 27.5904 +   command are required to change accordingly.
 27.5905 +
 27.5906 +   In most situations, the capabilities list in a given server state
 27.5907 +   will not change from session to session; for example, a given
 27.5908 +   extension will be installed permanently on a server.  Some clients
 27.5909 +   may therefore wish to remember which extensions a server supports to
 27.5910 +   avoid the delay of an additional command and response, particularly
 27.5911 +   if they open multiple connections in the same session.
 27.5912 +
 27.5913 +   However, information about extensions related to security and privacy
 27.5914 +   MUST NOT be cached, since this could allow a variety of attacks.
 27.5915 +
 27.5916 +   For example, consider a server that permits the use of cleartext
 27.5917 +   passwords on links that are encrypted but not otherwise:
 27.5918 +
 27.5919 +      [Initial connection set-up completed.]
 27.5920 +      [S] 200 NNTP Service Ready, posting permitted
 27.5921 +      [C] CAPABILITIES
 27.5922 +      [S] 101 Capability list:
 27.5923 +      [S] VERSION 2
 27.5924 +      [S] READER
 27.5925 +      [S] NEWNEWS
 27.5926 +      [S] POST
 27.5927 +      [S] XENCRYPT
 27.5928 +      [S] LIST ACTIVE NEWSGROUPS
 27.5929 +      [S] .
 27.5930 +      [C] XENCRYPT
 27.5931 +      [Client and server negotiate encryption on the link]
 27.5932 +      [S] 283 Encrypted link established
 27.5933 +
 27.5934 +
 27.5935 +
 27.5936 +Feather                     Standards Track                   [Page 106]
 27.5937 +
 27.5938 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5939 +
 27.5940 +
 27.5941 +      [C] CAPABILITIES
 27.5942 +      [S] 101 Capability list:
 27.5943 +      [S] VERSION 2
 27.5944 +      [S] READER
 27.5945 +      [S] NEWNEWS
 27.5946 +      [S] POST
 27.5947 +      [S] XSECRET
 27.5948 +      [S] LIST ACTIVE NEWSGROUPS
 27.5949 +      [S] .
 27.5950 +      [C] XSECRET fred flintstone
 27.5951 +      [S] 290 Password for fred accepted
 27.5952 +
 27.5953 +   If the client caches the last capabilities list, then on the next
 27.5954 +   session it will attempt to use XSECRET on an unencrypted link:
 27.5955 +
 27.5956 +      [Initial connection set-up completed.]
 27.5957 +      [S] 200 NNTP Service Ready, posting permitted
 27.5958 +      [C] XSECRET fred flintstone
 27.5959 +      [S] 483 Only permitted on secure links
 27.5960 +
 27.5961 +   This exposes the password to any eavesdropper.  While the primary
 27.5962 +   cause of this is passing a secret without first checking the security
 27.5963 +   of the link, caching of capability lists can increase the risk.
 27.5964 +
 27.5965 +   Any security extension should include requirements to check the
 27.5966 +   security state of the link in a manner appropriate to that extension.
 27.5967 +
 27.5968 +   Caching should normally only be considered for anonymous clients that
 27.5969 +   do not use any security or privacy extensions and for which the time
 27.5970 +   required for an additional command and response is a noticeable
 27.5971 +   issue.
 27.5972 +
 27.5973 +13.  Acknowledgements
 27.5974 +
 27.5975 +   This document is the result of much effort by the present and past
 27.5976 +   members of the NNTP Working Group, chaired by Russ Allbery and Ned
 27.5977 +   Freed.  It could not have been produced without them.
 27.5978 +
 27.5979 +   The author acknowledges the original authors of NNTP as documented in
 27.5980 +   RFC 977 [RFC977]: Brian Kantor and Phil Lapsey.
 27.5981 +
 27.5982 +   The author gratefully acknowledges the following:
 27.5983 +
 27.5984 +   o  The work of the NNTP committee chaired by Eliot Lear.  The
 27.5985 +      organization of this document was influenced by the last available
 27.5986 +      version from this working group.  A special thanks to Eliot for
 27.5987 +      generously providing the original machine-readable sources for
 27.5988 +      that document.
 27.5989 +
 27.5990 +
 27.5991 +
 27.5992 +Feather                     Standards Track                   [Page 107]
 27.5993 +
 27.5994 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.5995 +
 27.5996 +
 27.5997 +   o  The work of the DRUMS working group, specifically RFC 1869
 27.5998 +      [RFC1869], that drove the original thinking that led to the
 27.5999 +      CAPABILITIES command and the extensions mechanism detailed in this
 27.6000 +      document.
 27.6001 +
 27.6002 +   o  The authors of RFC 2616 [RFC2616] for providing specific and
 27.6003 +      relevant examples of security issues that should be considered for
 27.6004 +      HTTP.  Since many of the same considerations exist for NNTP, those
 27.6005 +      examples that are relevant have been included here with some minor
 27.6006 +      rewrites.
 27.6007 +
 27.6008 +   o  The comments and additional information provided by the following
 27.6009 +      individuals in preparing one or more of the progenitors of this
 27.6010 +      document:
 27.6011 +
 27.6012 +         Russ Allbery <rra@stanford.edu>
 27.6013 +         Wayne Davison <davison@armory.com>
 27.6014 +         Chris Lewis <clewis@bnr.ca>
 27.6015 +         Tom Limoncelli <tal@mars.superlink.net>
 27.6016 +         Eric Schnoebelen <eric@egsner.cirr.com>
 27.6017 +         Rich Salz <rsalz@osf.org>
 27.6018 +
 27.6019 +   This work was motivated by the work of various news reader authors
 27.6020 +   and news server authors, including those listed below:
 27.6021 +
 27.6022 +   Rick Adams
 27.6023 +      Original author of the NNTP extensions to the RN news reader and
 27.6024 +      last maintainer of Bnews.
 27.6025 +
 27.6026 +   Stan Barber
 27.6027 +      Original author of the NNTP extensions to the news readers that
 27.6028 +      are part of Bnews.
 27.6029 +
 27.6030 +   Geoff Collyer
 27.6031 +      Original author of the OVERVIEW database proposal and one of the
 27.6032 +      original authors of CNEWS.
 27.6033 +
 27.6034 +   Dan Curry
 27.6035 +      Original author of the xvnews news reader.
 27.6036 +
 27.6037 +   Wayne Davison
 27.6038 +      Author of the first threading extensions to the RN news reader
 27.6039 +      (commonly called TRN).
 27.6040 +
 27.6041 +   Geoff Huston
 27.6042 +      Original author of ANU NEWS.
 27.6043 +
 27.6044 +
 27.6045 +
 27.6046 +
 27.6047 +
 27.6048 +Feather                     Standards Track                   [Page 108]
 27.6049 +
 27.6050 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6051 +
 27.6052 +
 27.6053 +   Phil Lapsey
 27.6054 +      Original author of the UNIX reference implementation for NNTP.
 27.6055 +
 27.6056 +   Iain Lea
 27.6057 +      Original maintainer of the TIN news reader.
 27.6058 +
 27.6059 +   Chris Lewis
 27.6060 +      First known implementer of the AUTHINFO GENERIC extension.
 27.6061 +
 27.6062 +   Rich Salz
 27.6063 +      Original author of INN.
 27.6064 +
 27.6065 +   Henry Spencer
 27.6066 +      One of the original authors of CNEWS.
 27.6067 +
 27.6068 +   Kim Storm
 27.6069 +      Original author of the NN news reader.
 27.6070 +
 27.6071 +   Other people who contributed to this document include:
 27.6072 +
 27.6073 +      Matthias Andree
 27.6074 +      Greg Andruk
 27.6075 +      Daniel Barclay
 27.6076 +      Maurizio Codogno
 27.6077 +      Mark Crispin
 27.6078 +      Andrew Gierth
 27.6079 +      Juergen Helbing
 27.6080 +      Scott Hollenbeck
 27.6081 +      Urs Janssen
 27.6082 +      Charles Lindsey
 27.6083 +      Ade Lovett
 27.6084 +      David Magda
 27.6085 +      Ken Murchison
 27.6086 +      Francois Petillon
 27.6087 +      Peter Robinson
 27.6088 +      Rob Siemborski
 27.6089 +      Howard Swinehart
 27.6090 +      Ruud van Tol
 27.6091 +      Jeffrey Vinocur
 27.6092 +      Erik Warmelink
 27.6093 +
 27.6094 +   The author thanks them all and apologises to anyone omitted.
 27.6095 +
 27.6096 +   Finally, the present author gratefully acknowledges the vast amount
 27.6097 +   of work put into previous versions by the previous author:
 27.6098 +
 27.6099 +      Stan Barber <sob@academ.com>
 27.6100 +
 27.6101 +
 27.6102 +
 27.6103 +
 27.6104 +Feather                     Standards Track                   [Page 109]
 27.6105 +
 27.6106 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6107 +
 27.6108 +
 27.6109 +14.  References
 27.6110 +
 27.6111 +14.1.  Normative References
 27.6112 +
 27.6113 +   [ANSI1986]    American National Standards Institute, "Coded Character
 27.6114 +                 Set - 7-bit American Standard Code for Information
 27.6115 +                 Interchange", ANSI X3.4, 1986.
 27.6116 +
 27.6117 +   [RFC977]      Kantor, B. and P. Lapsley, "Network News Transfer
 27.6118 +                 Protocol", RFC 977, February 1986.
 27.6119 +
 27.6120 +   [RFC2045]     Freed, N. and N. Borenstein, "Multipurpose Internet
 27.6121 +                 Mail Extensions (MIME) Part One: Format of Internet
 27.6122 +                 Message Bodies", RFC 2045, November 1996.
 27.6123 +
 27.6124 +   [RFC2047]     Moore, K., "MIME (Multipurpose Internet Mail
 27.6125 +                 Extensions) Part Three: Message Header Extensions for
 27.6126 +                 Non-ASCII Text", RFC 2047, November 1996.
 27.6127 +
 27.6128 +   [RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
 27.6129 +                 Requirement Levels", BCP 14, RFC 2119, March 1997.
 27.6130 +
 27.6131 +   [RFC3629]     Yergeau, F., "UTF-8, a transformation format of ISO
 27.6132 +                 10646", STD 63, RFC 3629, November 2003.
 27.6133 +
 27.6134 +   [RFC4234]     Crocker, D., Ed. and P. Overell, "Augmented BNF for
 27.6135 +                 Syntax Specifications: ABNF", RFC 4234, October 2005.
 27.6136 +
 27.6137 +   [RFC4648]     Josefsson, S., "The Base16, Base32, and Base64 Data
 27.6138 +                 Encodings", RFC 4648, October 2006.
 27.6139 +
 27.6140 +   [TF.686-1]    International Telecommunications Union - Radio,
 27.6141 +                 "Glossary, ITU-R Recommendation TF.686-1",
 27.6142 +                 ITU-R Recommendation TF.686-1, October 1997.
 27.6143 +
 27.6144 +14.2.  Informative References
 27.6145 +
 27.6146 +   [NNTP-AUTH]   Vinocur, J., Murchison, K., and C. Newman, "Network
 27.6147 +                 News Transfer Protocol (NNTP) Extension for
 27.6148 +                 Authentication",
 27.6149 +                 RFC 4643, October 2006.
 27.6150 +
 27.6151 +   [NNTP-STREAM] Vinocur, J. and K. Murchison, "Network News Transfer
 27.6152 +                 Protocol (NNTP) Extension for Streaming Feeds",
 27.6153 +                 RFC 4644, October 2006.
 27.6154 +
 27.6155 +
 27.6156 +
 27.6157 +
 27.6158 +
 27.6159 +
 27.6160 +Feather                     Standards Track                   [Page 110]
 27.6161 +
 27.6162 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6163 +
 27.6164 +
 27.6165 +   [NNTP-TLS]    Murchison, K., Vinocur, J., and C. Newman, "Using
 27.6166 +                 Transport Layer Security (TLS) with Network News
 27.6167 +                 Transfer Protocol (NNTP)", RFC 4642, October 2006.
 27.6168 +
 27.6169 +   [RFC1036]     Horton, M. and R. Adams, "Standard for interchange of
 27.6170 +                 USENET messages", RFC 1036, December 1987.
 27.6171 +
 27.6172 +   [RFC1305]     Mills, D., "Network Time Protocol (Version 3)
 27.6173 +                 Specification, Implementation and Analysis", RFC 1305,
 27.6174 +                 March 1992.
 27.6175 +
 27.6176 +   [RFC1869]     Klensin, J., Freed, N., Rose, M., Stefferud, E., and D.
 27.6177 +                 Crocker, "SMTP Service Extensions", STD 10, RFC 1869,
 27.6178 +                 November 1995.
 27.6179 +
 27.6180 +   [RFC2616]     Fielding,  R., Gettys, J., Mogul, J., Frystyk, H.,
 27.6181 +                 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
 27.6182 +                 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
 27.6183 +
 27.6184 +   [RFC2629]     Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629,
 27.6185 +                 June 1999.
 27.6186 +
 27.6187 +   [RFC2822]     Resnick, P., "Internet Message Format", RFC 2822, April
 27.6188 +                 2001.
 27.6189 +
 27.6190 +   [RFC2980]     Barber, S., "Common NNTP Extensions", RFC 2980, October
 27.6191 +                 2000.
 27.6192 +
 27.6193 +   [ROBE1995]    Robertson, R., "FAQ: Overview database / NOV General
 27.6194 +                 Information", January 1995.
 27.6195 +
 27.6196 +                 There is no definitive copy of this document known to
 27.6197 +                 the author.  It was previously posted as the Usenet
 27.6198 +                 article <news:nov-faq-1-930909720@agate.Berkeley.EDU>
 27.6199 +
 27.6200 +   [SALZ1992]    Salz, R., "Manual Page for wildmat(3) from the INN 1.4
 27.6201 +                 distribution, Revision 1.10", April 1992.
 27.6202 +
 27.6203 +                 There is no definitive copy of this document known to
 27.6204 +                 the author.
 27.6205 +
 27.6206 +
 27.6207 +
 27.6208 +
 27.6209 +
 27.6210 +
 27.6211 +
 27.6212 +
 27.6213 +
 27.6214 +
 27.6215 +
 27.6216 +Feather                     Standards Track                   [Page 111]
 27.6217 +
 27.6218 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6219 +
 27.6220 +
 27.6221 +Appendix A.  Interaction with Other Specifications
 27.6222 +
 27.6223 +   NNTP is most often used for transferring articles that conform to
 27.6224 +   RFC 1036 [RFC1036] (such articles are called "Netnews articles"
 27.6225 +   here).  It is also sometimes used for transferring email messages
 27.6226 +   that conform to RFC 2822 [RFC2822] (such articles are called "email
 27.6227 +   articles" here).  In this situation, articles must conform both to
 27.6228 +   this specification and to that other one; this appendix describes
 27.6229 +   some relevant issues.
 27.6230 +
 27.6231 +A.1.  Header Folding
 27.6232 +
 27.6233 +   NNTP allows a header line to be folded (by inserting a CRLF pair)
 27.6234 +   before any space or TAB character.
 27.6235 +
 27.6236 +   Both email and Netnews articles are required to have at least one
 27.6237 +   octet other than space or TAB on each header line.  Thus, folding can
 27.6238 +   only happen at one point in each sequence of consecutive spaces or
 27.6239 +   TABs.  Netnews articles are further required to have the header name,
 27.6240 +   colon, and following space all on the first line; folding may only
 27.6241 +   happen beyond that space.  Finally, some non-conforming software will
 27.6242 +   remove trailing spaces and TABs from a line.  Therefore, it might be
 27.6243 +   inadvisable to fold a header after a space or TAB.
 27.6244 +
 27.6245 +   For maximum safety, header lines SHOULD conform to the following
 27.6246 +   syntax rather than to that in Section 9.7.
 27.6247 +
 27.6248 +
 27.6249 +     header = header-name ":" SP [header-content] CRLF
 27.6250 +     header-content = [WS] token *( [CRLF] WS token )
 27.6251 +
 27.6252 +A.2.  Message-IDs
 27.6253 +
 27.6254 +   Every article handled by an NNTP server MUST have a unique
 27.6255 +   message-id.  For the purposes of this specification, a message-id is
 27.6256 +   an arbitrary opaque string that merely needs to meet certain
 27.6257 +   syntactic requirements and is just a way to refer to the article.
 27.6258 +
 27.6259 +   Because there is a significant risk that old articles will be
 27.6260 +   reinjected into the global Usenet system, RFC 1036 [RFC1036] requires
 27.6261 +   that message-ids are globally unique for all time.
 27.6262 +
 27.6263 +   This specification states that message-ids are the same if and only
 27.6264 +   if they consist of the same sequence of octets.  Other specifications
 27.6265 +   may define two different sequences as being equal because they are
 27.6266 +   putting an interpretation on particular characters.  RFC 2822
 27.6267 +   [RFC2822] has a concept of "quoted" and "escaped" characters.  It
 27.6268 +   therefore considers the three message-ids:
 27.6269 +
 27.6270 +
 27.6271 +
 27.6272 +Feather                     Standards Track                   [Page 112]
 27.6273 +
 27.6274 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6275 +
 27.6276 +
 27.6277 +      <ab.cd@example.com>
 27.6278 +      <"ab.cd"@example.com>
 27.6279 +      <"ab.\cd"@example.com>
 27.6280 +
 27.6281 +   as being identical.  Therefore, an NNTP implementation handing email
 27.6282 +   articles must ensure that only one of these three appears in the
 27.6283 +   protocol and that the other two are converted to it as and when
 27.6284 +   necessary, such as when a client checks the results of a NEWNEWS
 27.6285 +   command against an internal database of message-ids.  Note that
 27.6286 +   RFC 1036 [RFC1036] never treats two different strings as being
 27.6287 +   identical.  Its successor (as of the time of writing) restricts the
 27.6288 +   syntax of message-ids so that, whenever RFC 2822 would treat two
 27.6289 +   strings as equivalent, only one of them is valid (in the above
 27.6290 +   example, only the first string is valid).
 27.6291 +
 27.6292 +   This specification does not describe how the message-id of an article
 27.6293 +   is determined; it may be deduced from the contents of the article or
 27.6294 +   derived from some external source.  If the server is also conforming
 27.6295 +   to another specification that contains a definition of message-id
 27.6296 +   compatible with this one, the server SHOULD use those message-ids.  A
 27.6297 +   common approach, and one that SHOULD be used for email and Netnews
 27.6298 +   articles, is to extract the message-id from the contents of a header
 27.6299 +   with name "Message-ID".  This may not be as simple as copying the
 27.6300 +   entire header contents; it may be necessary to strip off comments and
 27.6301 +   undo quoting, or to reduce "equivalent" message-ids to a canonical
 27.6302 +   form.
 27.6303 +
 27.6304 +   If an article is obtained through the IHAVE command, there will be a
 27.6305 +   message-id provided with the command.  The server MAY either use it
 27.6306 +   or determine one from the article contents.  However, whichever it
 27.6307 +   does, it SHOULD ensure that, if the IHAVE command is repeated with
 27.6308 +   the same argument and article, it will be recognized as a duplicate.
 27.6309 +
 27.6310 +   If an article does not contain a message-id that the server can
 27.6311 +   identify, it MUST synthesize one.  This could, for example, be a
 27.6312 +   simple sequence number or be based on the date and time when the
 27.6313 +   article arrived.  When email or Netnews articles are handled, a
 27.6314 +   Message-ID header SHOULD be added to ensure global consistency and
 27.6315 +   uniqueness.
 27.6316 +
 27.6317 +   Note that, because the message-id might not have been derived from
 27.6318 +   the Message-ID header in the article, the following example is
 27.6319 +   legitimate (though unusual):
 27.6320 +
 27.6321 +
 27.6322 +
 27.6323 +
 27.6324 +
 27.6325 +
 27.6326 +
 27.6327 +
 27.6328 +Feather                     Standards Track                   [Page 113]
 27.6329 +
 27.6330 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6331 +
 27.6332 +
 27.6333 +      [C] HEAD <45223423@example.com>
 27.6334 +      [S] 221 0 <45223423@example.com>
 27.6335 +      [S] Path: pathost!demo!whitehouse!not-for-mail
 27.6336 +      [S] Message-ID: <1234@example.net>
 27.6337 +      [S] From: "Demo User" <nobody@example.net>
 27.6338 +      [S] Newsgroups: misc.test
 27.6339 +      [S] Subject: I am just a test article
 27.6340 +      [S] Date: 6 Oct 1998 04:38:40 -0500
 27.6341 +      [S] Organization: An Example Net, Uncertain, Texas
 27.6342 +      [S] .
 27.6343 +
 27.6344 +A.3.  Article Posting
 27.6345 +
 27.6346 +   As far as NNTP is concerned, the POST and IHAVE commands provide the
 27.6347 +   same basic facilities in a slightly different way.  However, they
 27.6348 +   have rather different intentions.
 27.6349 +
 27.6350 +   The IHAVE command is intended for transmitting conforming articles
 27.6351 +   between a system of NNTP servers, with all articles perhaps also
 27.6352 +   conforming to another specification (e.g., all articles are Netnews
 27.6353 +   articles).  It is expected that the client will already have done any
 27.6354 +   necessary validation (or that it has in turn obtained the article
 27.6355 +   from a third party that has done so); therefore, the contents SHOULD
 27.6356 +   be left unchanged.
 27.6357 +
 27.6358 +   In contrast, the POST command is intended for use when an end-user is
 27.6359 +   injecting a newly created article into a such a system.  The article
 27.6360 +   being transferred might not be a conforming email or Netnews article,
 27.6361 +   and the server is expected to validate it and, if necessary, to
 27.6362 +   convert it to the right form for onward distribution.  This is often
 27.6363 +   done by a separate piece of software on the server installation; if
 27.6364 +   so, the NNTP server SHOULD pass the incoming article to that software
 27.6365 +   unaltered, making no attempt to filter characters, to fold or limit
 27.6366 +   lines, or to process the incoming text otherwise.
 27.6367 +
 27.6368 +   The POST command can fail in various ways, and clients should be
 27.6369 +   prepared to re-send an article.  When doing so, however, it is often
 27.6370 +   important to ensure (as far as possible) that the same message-id is
 27.6371 +   allocated to both attempts so that the server, or other servers, can
 27.6372 +   recognize the two articles as duplicates.  In the case of email or
 27.6373 +   Netnews articles, therefore, the posted article SHOULD contain a
 27.6374 +   header with the name "Message-ID", and the contents of this header
 27.6375 +   SHOULD be identical on each attempt.  The server SHOULD ensure that
 27.6376 +   two POSTed articles with the same contents for this header are
 27.6377 +   recognized as identical and that the same message-id is allocated,
 27.6378 +   whether or not those contents are suitable for use as the message-id.
 27.6379 +
 27.6380 +
 27.6381 +
 27.6382 +
 27.6383 +
 27.6384 +Feather                     Standards Track                   [Page 114]
 27.6385 +
 27.6386 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6387 +
 27.6388 +
 27.6389 +Appendix B.  Summary of Commands
 27.6390 +
 27.6391 +   This section contains a list of every command defined in this
 27.6392 +   document, ordered by command name and by indicating capability.
 27.6393 +
 27.6394 +                         Ordered by command name:
 27.6395 +
 27.6396 +       +-------------------+-----------------------+---------------+
 27.6397 +       | Command           | Indicating capability | Definition    |
 27.6398 +       +-------------------+-----------------------+---------------+
 27.6399 +       | ARTICLE           | READER                | Section 6.2.1 |
 27.6400 +       | BODY              | READER                | Section 6.2.3 |
 27.6401 +       | CAPABILITIES      | mandatory             | Section 5.2   |
 27.6402 +       | DATE              | READER                | Section 7.1   |
 27.6403 +       | GROUP             | READER                | Section 6.1.1 |
 27.6404 +       | HDR               | HDR                   | Section 8.5   |
 27.6405 +       | HEAD              | mandatory             | Section 6.2.2 |
 27.6406 +       | HELP              | mandatory             | Section 7.2   |
 27.6407 +       | IHAVE             | IHAVE                 | Section 6.3.2 |
 27.6408 +       | LAST              | READER                | Section 6.1.3 |
 27.6409 +       | LIST              | LIST                  | Section 7.6.1 |
 27.6410 +       | LIST ACTIVE.TIMES | LIST                  | Section 7.6.4 |
 27.6411 +       | LIST ACTIVE       | LIST                  | Section 7.6.3 |
 27.6412 +       | LIST DISTRIB.PATS | LIST                  | Section 7.6.5 |
 27.6413 +       | LIST HEADERS      | HDR                   | Section 8.6   |
 27.6414 +       | LIST NEWSGROUPS   | LIST                  | Section 7.6.6 |
 27.6415 +       | LIST OVERVIEW.FMT | OVER                  | Section 8.4   |
 27.6416 +       | LISTGROUP         | READER                | Section 6.1.2 |
 27.6417 +       | MODE READER       | MODE-READER           | Section 5.3   |
 27.6418 +       | NEWGROUPS         | READER                | Section 7.3   |
 27.6419 +       | NEWNEWS           | NEWNEWS               | Section 7.4   |
 27.6420 +       | NEXT              | READER                | Section 6.1.4 |
 27.6421 +       | OVER              | OVER                  | Section 8.3   |
 27.6422 +       | POST              | POST                  | Section 6.3.1 |
 27.6423 +       | QUIT              | mandatory             | Section 5.4   |
 27.6424 +       | STAT              | mandatory             | Section 6.2.4 |
 27.6425 +       +-------------------+-----------------------+---------------+
 27.6426 +
 27.6427 +
 27.6428 +
 27.6429 +
 27.6430 +
 27.6431 +
 27.6432 +
 27.6433 +
 27.6434 +
 27.6435 +
 27.6436 +
 27.6437 +
 27.6438 +
 27.6439 +
 27.6440 +Feather                     Standards Track                   [Page 115]
 27.6441 +
 27.6442 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6443 +
 27.6444 +
 27.6445 +                     Ordered by indicating capability:
 27.6446 +
 27.6447 +       +-------------------+-----------------------+---------------+
 27.6448 +       | Command           | Indicating capability | Definition    |
 27.6449 +       +-------------------+-----------------------+---------------+
 27.6450 +       | CAPABILITIES      | mandatory             | Section 5.2   |
 27.6451 +       | HEAD              | mandatory             | Section 6.2.2 |
 27.6452 +       | HELP              | mandatory             | Section 7.2   |
 27.6453 +       | QUIT              | mandatory             | Section 5.4   |
 27.6454 +       | STAT              | mandatory             | Section 6.2.4 |
 27.6455 +       | HDR               | HDR                   | Section 8.5   |
 27.6456 +       | LIST HEADERS      | HDR                   | Section 8.6   |
 27.6457 +       | IHAVE             | IHAVE                 | Section 6.3.2 |
 27.6458 +       | LIST              | LIST                  | Section 7.6.1 |
 27.6459 +       | LIST ACTIVE       | LIST                  | Section 7.6.3 |
 27.6460 +       | LIST ACTIVE.TIMES | LIST                  | Section 7.6.4 |
 27.6461 +       | LIST DISTRIB.PATS | LIST                  | Section 7.6.5 |
 27.6462 +       | LIST NEWSGROUPS   | LIST                  | Section 7.6.6 |
 27.6463 +       | MODE READER       | MODE-READER           | Section 5.3   |
 27.6464 +       | NEWNEWS           | NEWNEWS               | Section 7.4   |
 27.6465 +       | OVER              | OVER                  | Section 8.3   |
 27.6466 +       | LIST OVERVIEW.FMT | OVER                  | Section 8.4   |
 27.6467 +       | POST              | POST                  | Section 6.3.1 |
 27.6468 +       | ARTICLE           | READER                | Section 6.2.1 |
 27.6469 +       | BODY              | READER                | Section 6.2.3 |
 27.6470 +       | DATE              | READER                | Section 7.1   |
 27.6471 +       | GROUP             | READER                | Section 6.1.1 |
 27.6472 +       | LAST              | READER                | Section 6.1.3 |
 27.6473 +       | LISTGROUP         | READER                | Section 6.1.2 |
 27.6474 +       | NEWGROUPS         | READER                | Section 7.3   |
 27.6475 +       | NEXT              | READER                | Section 6.1.4 |
 27.6476 +       +-------------------+-----------------------+---------------+
 27.6477 +
 27.6478 +
 27.6479 +
 27.6480 +
 27.6481 +
 27.6482 +
 27.6483 +
 27.6484 +
 27.6485 +
 27.6486 +
 27.6487 +
 27.6488 +
 27.6489 +
 27.6490 +
 27.6491 +
 27.6492 +
 27.6493 +
 27.6494 +
 27.6495 +
 27.6496 +Feather                     Standards Track                   [Page 116]
 27.6497 +
 27.6498 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6499 +
 27.6500 +
 27.6501 +Appendix C.  Summary of Response Codes
 27.6502 +
 27.6503 +   This section contains a list of every response code defined in this
 27.6504 +   document and indicates whether it is multi-line, which commands can
 27.6505 +   generate it, what arguments it has, and what its meaning is.
 27.6506 +
 27.6507 +   Response code 100 (multi-line)
 27.6508 +      Generated by: HELP
 27.6509 +      Meaning: help text follows.
 27.6510 +
 27.6511 +   Response code 101 (multi-line)
 27.6512 +      Generated by: CAPABILITIES
 27.6513 +      Meaning: capabilities list follows.
 27.6514 +
 27.6515 +   Response code 111
 27.6516 +      Generated by: DATE
 27.6517 +      1 argument: yyyymmddhhmmss
 27.6518 +      Meaning: server date and time.
 27.6519 +
 27.6520 +   Response code 200
 27.6521 +      Generated by: initial connection, MODE READER
 27.6522 +      Meaning: service available, posting allowed.
 27.6523 +
 27.6524 +   Response code 201
 27.6525 +      Generated by: initial connection, MODE READER
 27.6526 +      Meaning: service available, posting prohibited.
 27.6527 +
 27.6528 +   Response code 205
 27.6529 +      Generated by: QUIT
 27.6530 +      Meaning: connection closing (the server immediately closes the
 27.6531 +      connection).
 27.6532 +
 27.6533 +   Response code 211
 27.6534 +      The 211 response code has two completely different forms,
 27.6535 +      depending on which command generated it:
 27.6536 +
 27.6537 +         (not multi-line)
 27.6538 +         Generated by: GROUP
 27.6539 +         4 arguments: number low high group
 27.6540 +         Meaning: group selected.
 27.6541 +
 27.6542 +         (multi-line)
 27.6543 +         Generated by: LISTGROUP
 27.6544 +         4 arguments: number low high group
 27.6545 +         Meaning: article numbers follow.
 27.6546 +
 27.6547 +
 27.6548 +
 27.6549 +
 27.6550 +
 27.6551 +
 27.6552 +Feather                     Standards Track                   [Page 117]
 27.6553 +
 27.6554 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6555 +
 27.6556 +
 27.6557 +   Response code 215 (multi-line)
 27.6558 +      Generated by: LIST
 27.6559 +      Meaning: information follows.
 27.6560 +
 27.6561 +   Response code 220 (multi-line)
 27.6562 +      Generated by: ARTICLE
 27.6563 +      2 arguments: n message-id
 27.6564 +      Meaning: article follows.
 27.6565 +
 27.6566 +   Response code 221 (multi-line)
 27.6567 +      Generated by: HEAD
 27.6568 +      2 arguments: n message-id
 27.6569 +      Meaning: article headers follow.
 27.6570 +
 27.6571 +   Response code 222 (multi-line)
 27.6572 +      Generated by: BODY
 27.6573 +      2 arguments: n message-id
 27.6574 +      Meaning: article body follows.
 27.6575 +
 27.6576 +   Response code 223
 27.6577 +      Generated by: LAST, NEXT, STAT
 27.6578 +      2 arguments: n message-id
 27.6579 +      Meaning: article exists and selected.
 27.6580 +
 27.6581 +   Response code 224 (multi-line)
 27.6582 +      Generated by: OVER
 27.6583 +      Meaning: overview information follows.
 27.6584 +
 27.6585 +   Response code 225 (multi-line)
 27.6586 +      Generated by: HDR
 27.6587 +      Meaning: headers follow.
 27.6588 +
 27.6589 +   Response code 230 (multi-line)
 27.6590 +      Generated by: NEWNEWS
 27.6591 +      Meaning: list of new articles follows.
 27.6592 +
 27.6593 +   Response code 231 (multi-line)
 27.6594 +      Generated by: NEWGROUPS
 27.6595 +      Meaning: list of new newsgroups follows.
 27.6596 +
 27.6597 +   Response code 235
 27.6598 +      Generated by: IHAVE (second stage)
 27.6599 +      Meaning: article transferred OK.
 27.6600 +
 27.6601 +   Response code 240
 27.6602 +      Generated by: POST (second stage)
 27.6603 +      Meaning: article received OK.
 27.6604 +
 27.6605 +
 27.6606 +
 27.6607 +
 27.6608 +Feather                     Standards Track                   [Page 118]
 27.6609 +
 27.6610 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6611 +
 27.6612 +
 27.6613 +   Response code 335
 27.6614 +      Generated by: IHAVE (first stage)
 27.6615 +      Meaning: send article to be transferred.
 27.6616 +
 27.6617 +   Response code 340
 27.6618 +      Generated by: POST (first stage)
 27.6619 +      Meaning: send article to be posted.
 27.6620 +
 27.6621 +   Response code 400
 27.6622 +      Generic response and generated by initial connection
 27.6623 +      Meaning: service not available or no longer available (the server
 27.6624 +      immediately closes the connection).
 27.6625 +
 27.6626 +   Response code 401
 27.6627 +      Generic response
 27.6628 +      1 argument: capability-label
 27.6629 +      Meaning: the server is in the wrong mode; the indicated capability
 27.6630 +      should be used to change the mode.
 27.6631 +
 27.6632 +   Response code 403
 27.6633 +      Generic response
 27.6634 +      Meaning: internal fault or problem preventing action being taken.
 27.6635 +
 27.6636 +   Response code 411
 27.6637 +      Generated by: GROUP, LISTGROUP
 27.6638 +      Meaning: no such newsgroup.
 27.6639 +
 27.6640 +   Response code 412
 27.6641 +      Generated by: ARTICLE, BODY, GROUP, HDR, HEAD, LAST, LISTGROUP,
 27.6642 +      NEXT, OVER, STAT
 27.6643 +      Meaning: no newsgroup selected.
 27.6644 +
 27.6645 +   Response code 420
 27.6646 +      Generated by: ARTICLE, BODY, HDR, HEAD, LAST, NEXT, OVER, STAT
 27.6647 +      Meaning: current article number is invalid.
 27.6648 +
 27.6649 +   Response code 421
 27.6650 +      Generated by: NEXT
 27.6651 +      Meaning: no next article in this group.
 27.6652 +
 27.6653 +   Response code 422
 27.6654 +      Generated by: LAST
 27.6655 +      Meaning: no previous article in this group.
 27.6656 +
 27.6657 +   Response code 423
 27.6658 +      Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT
 27.6659 +      Meaning: no article with that number or in that range.
 27.6660 +
 27.6661 +
 27.6662 +
 27.6663 +
 27.6664 +Feather                     Standards Track                   [Page 119]
 27.6665 +
 27.6666 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6667 +
 27.6668 +
 27.6669 +   Response code 430
 27.6670 +      Generated by: ARTICLE, BODY, HDR, HEAD, OVER, STAT
 27.6671 +      Meaning: no article with that message-id.
 27.6672 +
 27.6673 +   Response code 435
 27.6674 +      Generated by: IHAVE (first stage)
 27.6675 +      Meaning: article not wanted.
 27.6676 +
 27.6677 +   Response code 436
 27.6678 +      Generated by: IHAVE (either stage)
 27.6679 +      Meaning: transfer not possible (first stage) or failed (second
 27.6680 +      stage); try again later.
 27.6681 +
 27.6682 +   Response code 437
 27.6683 +      Generated by: IHAVE (second stage)
 27.6684 +      Meaning: transfer rejected; do not retry.
 27.6685 +
 27.6686 +   Response code 440
 27.6687 +      Generated by: POST (first stage)
 27.6688 +      Meaning: posting not permitted.
 27.6689 +
 27.6690 +   Response code 441
 27.6691 +      Generated by: POST (second stage)
 27.6692 +      Meaning: posting failed.
 27.6693 +
 27.6694 +   Response code 480
 27.6695 +      Generic response
 27.6696 +      Meaning: command unavailable until the client has authenticated
 27.6697 +      itself.
 27.6698 +
 27.6699 +   Response code 483
 27.6700 +      Generic response
 27.6701 +      Meaning: command unavailable until suitable privacy has been
 27.6702 +      arranged.
 27.6703 +
 27.6704 +   Response code 500
 27.6705 +      Generic response
 27.6706 +      Meaning: unknown command.
 27.6707 +
 27.6708 +   Response code 501
 27.6709 +      Generic response
 27.6710 +      Meaning: syntax error in command.
 27.6711 +
 27.6712 +
 27.6713 +
 27.6714 +
 27.6715 +
 27.6716 +
 27.6717 +
 27.6718 +
 27.6719 +
 27.6720 +Feather                     Standards Track                   [Page 120]
 27.6721 +
 27.6722 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6723 +
 27.6724 +
 27.6725 +   Response code 502
 27.6726 +      Generic response and generated by initial connection
 27.6727 +
 27.6728 +      Meaning for the initial connection and the MODE READER command:
 27.6729 +      service permanently unavailable (the server immediately closes the
 27.6730 +      connection).
 27.6731 +
 27.6732 +      Meaning for all other commands: command not permitted (and there
 27.6733 +      is no way for the client to change this).
 27.6734 +
 27.6735 +   Response code 503
 27.6736 +      Generic response
 27.6737 +      Meaning: feature not supported.
 27.6738 +
 27.6739 +   Response code 504
 27.6740 +      Generic response
 27.6741 +      Meaning: error in base64-encoding [RFC4648] of an argument.
 27.6742 +
 27.6743 +Appendix D.  Changes from RFC 977
 27.6744 +
 27.6745 +   In general every attempt has been made to ensure that the protocol
 27.6746 +   specification in this document is compatible with the version
 27.6747 +   specified in RFC 977 [RFC977] and the various facilities adopted from
 27.6748 +   RFC 2980 [RFC2980].  However, there have been a number of changes,
 27.6749 +   some compatible and some not.
 27.6750 +
 27.6751 +   This appendix lists these changes.  It is not guaranteed to be
 27.6752 +   exhaustive or correct and MUST NOT be relied on.
 27.6753 +
 27.6754 +   o  A formal syntax specification (Section 9) has been added.
 27.6755 +
 27.6756 +   o  The default character set is changed from US-ASCII [ANSI1986] to
 27.6757 +      UTF-8 [RFC3629] (note that US-ASCII is a subset of UTF-8).  This
 27.6758 +      matter is discussed further in Section 10.
 27.6759 +
 27.6760 +   o  All articles are required to have a message-id, eliminating the
 27.6761 +      "<0>" placeholder used in RFC 977 in some responses.
 27.6762 +
 27.6763 +   o  The newsgroup name matching capabilities already documented in
 27.6764 +      RFC 977 ("wildmats", Section 4) are clarified and extended.  The
 27.6765 +      new facilities (e.g., the use of commas and exclamation marks) are
 27.6766 +      allowed wherever wildmats appear in the protocol.
 27.6767 +
 27.6768 +   o  Support for pipelining of commands (Section 3.5) is made
 27.6769 +      mandatory.
 27.6770 +
 27.6771 +
 27.6772 +
 27.6773 +
 27.6774 +
 27.6775 +
 27.6776 +Feather                     Standards Track                   [Page 121]
 27.6777 +
 27.6778 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6779 +
 27.6780 +
 27.6781 +   o  The principles behind response codes (Section 3.2) have been
 27.6782 +      tidied up.  In particular:
 27.6783 +
 27.6784 +      *  the x8x response code family, formerly used for private
 27.6785 +         extensions, is now reserved for authentication and privacy
 27.6786 +         extensions;
 27.6787 +
 27.6788 +      *  the x9x response code family, formerly intended for debugging
 27.6789 +         facilities, are now reserved for private extensions;
 27.6790 +
 27.6791 +      *  the 502 and 503 generic response codes (Section 3.2.1) have
 27.6792 +         been redefined;
 27.6793 +
 27.6794 +      *  new 401, 403, 480, 483, and 504 generic response codes have
 27.6795 +         been added.
 27.6796 +
 27.6797 +   o  The rules for article numbering (Section 6) have been clarified
 27.6798 +      (also see Section 6.1.1.2).
 27.6799 +
 27.6800 +   o  The SLAVE command (which was ill-defined) is removed from the
 27.6801 +      protocol.
 27.6802 +
 27.6803 +   o  Four-digit years are permitted in the NEWNEWS (Section 7.4) and
 27.6804 +      NEWGROUPS (Section 7.3) commands (two-digit years are still
 27.6805 +      permitted).  The optional distribution parameter to these commands
 27.6806 +      has been removed.
 27.6807 +
 27.6808 +   o  The LIST command (Section 7.6.1) is greatly extended; the original
 27.6809 +      is available as LIST ACTIVE, while new variants include
 27.6810 +      ACTIVE.TIMES, DISTRIB.PATS, and NEWSGROUPS.  A new "m" status flag
 27.6811 +      is added to the LIST ACTIVE response.
 27.6812 +
 27.6813 +   o  A new CAPABILITIES command (Section 5.2) allows clients to
 27.6814 +      determine what facilities are supported by a server.
 27.6815 +
 27.6816 +   o  The DATE command (Section 7.1) is adopted from RFC 2980
 27.6817 +      effectively unchanged.
 27.6818 +
 27.6819 +   o  The LISTGROUP command (Section 6.1.2) is adopted from RFC 2980.
 27.6820 +      An optional range argument has been added, and the 211 initial
 27.6821 +      response line now has the same format as the 211 response from the
 27.6822 +      GROUP command.
 27.6823 +
 27.6824 +   o  The MODE READER command (Section 5.3) is adopted from RFC 2980 and
 27.6825 +      its meaning and effects clarified.
 27.6826 +
 27.6827 +   o  The XHDR command in RFC 2980 has been formalised as the new HDR
 27.6828 +      (Section 8.5) and LIST HEADERS (Section 8.6) commands.
 27.6829 +
 27.6830 +
 27.6831 +
 27.6832 +Feather                     Standards Track                   [Page 122]
 27.6833 +
 27.6834 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6835 +
 27.6836 +
 27.6837 +   o  The XOVER command in RFC 2980 has been formalised as the new OVER
 27.6838 +      (Section 8.3) and LIST OVERVIEW.FMT (Section 8.4) commands.  The
 27.6839 +      former can be applied to a message-id as well as to a range.
 27.6840 +
 27.6841 +   o  The concept of article metadata (Section 8.1) has been formalised,
 27.6842 +      allowing the Bytes and Lines pseudo-headers to be deprecated.
 27.6843 +
 27.6844 +   Client authors should note in particular that lack of support for the
 27.6845 +   CAPABILITIES command is a good indication that the server does not
 27.6846 +   support this specification.
 27.6847 +
 27.6848 +
 27.6849 +
 27.6850 +
 27.6851 +
 27.6852 +
 27.6853 +
 27.6854 +
 27.6855 +
 27.6856 +
 27.6857 +
 27.6858 +
 27.6859 +
 27.6860 +
 27.6861 +
 27.6862 +
 27.6863 +
 27.6864 +
 27.6865 +
 27.6866 +
 27.6867 +
 27.6868 +
 27.6869 +
 27.6870 +
 27.6871 +
 27.6872 +
 27.6873 +
 27.6874 +
 27.6875 +
 27.6876 +
 27.6877 +
 27.6878 +
 27.6879 +
 27.6880 +
 27.6881 +
 27.6882 +
 27.6883 +
 27.6884 +
 27.6885 +
 27.6886 +
 27.6887 +
 27.6888 +Feather                     Standards Track                   [Page 123]
 27.6889 +
 27.6890 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6891 +
 27.6892 +
 27.6893 +Author's Address
 27.6894 +
 27.6895 +   Clive D.W. Feather
 27.6896 +   THUS plc
 27.6897 +   322 Regents Park Road
 27.6898 +   London
 27.6899 +   N3  2QQ
 27.6900 +   United Kingdom
 27.6901 +
 27.6902 +   Phone: +44 20 8495 6138
 27.6903 +   Fax:   +44 870 051 9937
 27.6904 +   EMail: clive@demon.net
 27.6905 +   URI:   http://www.davros.org/
 27.6906 +
 27.6907 +
 27.6908 +
 27.6909 +
 27.6910 +
 27.6911 +
 27.6912 +
 27.6913 +
 27.6914 +
 27.6915 +
 27.6916 +
 27.6917 +
 27.6918 +
 27.6919 +
 27.6920 +
 27.6921 +
 27.6922 +
 27.6923 +
 27.6924 +
 27.6925 +
 27.6926 +
 27.6927 +
 27.6928 +
 27.6929 +
 27.6930 +
 27.6931 +
 27.6932 +
 27.6933 +
 27.6934 +
 27.6935 +
 27.6936 +
 27.6937 +
 27.6938 +
 27.6939 +
 27.6940 +
 27.6941 +
 27.6942 +
 27.6943 +
 27.6944 +Feather                     Standards Track                   [Page 124]
 27.6945 +
 27.6946 +RFC 3977         Network News Transfer Protocol (NNTP)      October 2006
 27.6947 +
 27.6948 +
 27.6949 +Full Copyright Statement
 27.6950 +
 27.6951 +Copyright (C) The Internet Society (2006).
 27.6952 +
 27.6953 +   This document is subject to the rights, licenses and restrictions
 27.6954 +   contained in BCP 78, and except as set forth therein, the authors
 27.6955 +   retain all their rights.
 27.6956 +
 27.6957 +   This document and the information contained herein are provided on an
 27.6958 +   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
 27.6959 +   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
 27.6960 +   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
 27.6961 +   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
 27.6962 +   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
 27.6963 +   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 27.6964 +
 27.6965 +Intellectual Property
 27.6966 +
 27.6967 +   The IETF takes no position regarding the validity or scope of any
 27.6968 +   Intellectual Property Rights or other rights that might be claimed to
 27.6969 +   pertain to the implementation or use of the technology described in
 27.6970 +   this document or the extent to which any license under such rights
 27.6971 +   might or might not be available; nor does it represent that it has
 27.6972 +   made any independent effort to identify any such rights.  Information
 27.6973 +   on the procedures with respect to rights in RFC documents can be
 27.6974 +   found in BCP 78 and BCP 79.
 27.6975 +
 27.6976 +   Copies of IPR disclosures made to the IETF Secretariat and any
 27.6977 +   assurances of licenses to be made available, or the result of an
 27.6978 +   attempt made to obtain a general license or permission for the use of
 27.6979 +   such proprietary rights by implementers or users of this
 27.6980 +   specification can be obtained from the IETF on-line IPR repository at
 27.6981 +   http://www.ietf.org/ipr.
 27.6982 +
 27.6983 +   The IETF invites any interested party to bring to its attention any
 27.6984 +   copyrights, patents or patent applications, or other proprietary
 27.6985 +   rights that may cover technology that may be required to implement
 27.6986 +   this standard.  Please address the information to the IETF at ietf-
 27.6987 +   ipr@ietf.org.
 27.6988 +
 27.6989 +Acknowledgement
 27.6990 +
 27.6991 +   Funding for the RFC Editor function is provided by the IETF
 27.6992 +   Administrative Support Activity (IASA).
 27.6993 +
 27.6994 +
 27.6995 +
 27.6996 +
 27.6997 +
 27.6998 +
 27.6999 +
 27.7000 +Feather                     Standards Track                   [Page 125]
 27.7001 +
    28.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    28.2 +++ b/trunk/test/StringTemplateTest.java	Tue Jan 20 10:21:03 2009 +0100
    28.3 @@ -0,0 +1,26 @@
    28.4 +/*
    28.5 + * To change this template, choose Tools | Templates
    28.6 + * and open the template in the editor.
    28.7 + */
    28.8 +
    28.9 +package test;
   28.10 +
   28.11 +import com.so.news.util.StringTemplate;
   28.12 +
   28.13 +/**
   28.14 + *
   28.15 + * @author chris
   28.16 + */
   28.17 +public class StringTemplateTest 
   28.18 +{
   28.19 +  public static void main(String[] args)
   28.20 +  {
   28.21 +    StringTemplate templ 
   28.22 +      = new StringTemplate("SELECT %row FROM %table WHERE %row = ich");
   28.23 +    
   28.24 +    templ.set("row", "name");
   28.25 +    templ.set("table", "UserTable");
   28.26 +    
   28.27 +    System.out.println(templ.toString());
   28.28 +  }
   28.29 +}