Text 10027, 481 rader
Skriven 2018-02-15 20:08:38 av Markus Reschke (2:240/1661)
Ärende: review of FSP-1040
==========================
Hi!

This is meant to be an experiment about public feedback for a new FSP. The idea
is to ask you for help on reviewing the FSP regarding grammar/spelling errors
and technical details we might have missed or got wrong. It's not about
discussing why something is defined this way and not that way, and other
similar things. I don't know if you have experience with collaborating on
documents. If you have you know it becomes more complex as more people are
involved. So please focus on the main task.

Here we go:

**********************************************************************
FTSC                             FIDONET TECHNICAL STANDARDS COMMITTEE
**********************************************************************

Publication:    FSP-1040
Revision:       1
Title:          SRIF file request interface
Authors:        Markus Reschke, FTSC members
Date:           2017-12-13
----------------------------------------------------------------------

Contents
--------
                1. Definitions
                2. SRIF
                   2.1 Introduction
                   2.2 Description
                   2.3 SRIF Format 
                   2.4 Required Keywords
                   2.5 Optional Keywords
                A. References
                B. History
----------------------------------------------------------------------

Status of this document
-----------------------

   This document is a Fidonet Standard Proposal (FSP) - it specifies
   the current technical requirements and recommendations for FTN
   software developers, coordinators and sysops of the Fidonet network
   and other networks using FTN technology.

   This document is released to the public domain, and may be used,
   copied or modified for any purpose whatever.


1. Definitions
--------------

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
   NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
   in this document are to be interpreted as described in [FTA-1006].

   Filepath:
     The complete filepath of a file, i.e. path and file name.

   Text file:
     A file containing text characters. Since all keywords are based
     on the ASCII character encoding the format is assumed to be 
     compatible with most other character encodings.


2. SRIF
-------

2.1 Introduction
----------------

SRIF (Standard Request Information File) was developed to be a
standard interface to run external file request processors by mailers.
A standard interface provides more operational flexibility for sysops.
For example, a system can run different mailers for Internet and POTS
lines while using the same file request processor.

Originally SRIF was defined in FSC-0086. But that document is
protected by copyright and can't be simply amended by the FTSC. Also
it lacks some technical details, and new keywords were introduced
meanwhile. This new document intends to fix the shortcomings.


2.2 Description
---------------

The SRIF is a simple text file created by the mailer after receiving
an file request, and contains information for the file request
processor. It includes the filepath of the file request (.REQ file)
and the filepath of a response file besides other information. The
file request processor reads the SRIF, processes the file request,
and writes a list of files found to the response file. After the file
request processor has finished the mailer reads the response file
and sends the files listed.

The SRIF process in more detail:

When the mailer receives a .REQ file request from a calling system it
performs following tasks:
- creates a unique response file
- creates a unique SRIF
- writes all required data to the SRIF, also optional data
- executes the file request processor with the SRIF's filepath as
  command line parameter,
  and waits until the file request processor has finished
- processes the response file and sends the files found
- deletes the SRIF and the response file

The file request processor performs following tasks when executed:
- gets the SRIF's filepath from the command line
- reads its own configuration
- reads the SRIF
- reads and processes the file request file,
  and writes files found to the response file
- may create user feedback, e.g. a netmail packet, and add that to
  the the response file too
  hint: feedback has be a unique file also

The files created need to be unique to support a multi line or
multitasking system. It's up to the software developer to implement
a method ensuring unique files. Some operating systems offer library
functions for that purpose. If you use one of those, select a safe
function which minimizes the risk of race conditions.


2.3 SRIF Format
---------------

As already mentioned, the SRIF is a simple text file containing
information for the file request processor. Each line consists of a
keyword-value pair. The line termination isn't specified, so it could
be CR (Carriage Return, ASCII 0x0D), LF (Line Feed, ASCII 0x0A) or
CR-LF. The file request processor should support all three variations.
Empty lines should be avoided by the mailer, but tolerated by the file
request processor. The syntax for each line is:

  <keyword><space><value or string>

Space is ASCII 0x20. A string can include spaces, for example 
'sysop name'.

Keywords are divided into two groups, i.e. required and optional
keywords. Required keywords must be given by the mailer, and optional
keywords may be given. Each keyword must not be used more than one
time, unless stated otherwise in the keyword's description. Keywords
must not contain any whitespace characters.

The order of the keywords in the SRIF isn't defined. Therefore the
file request processor must be able to accept any order. It should
also ignore unknown and unsupported keywords.


2.4 Required Keywords
---------------------

The SRIF must include the following keywords:


Sysop

  Name of the calling sysop.

  Syntax: Sysop <sysop name>
  Example: Sysop Jane Doe  


AKA

  FTS address of calling system. This keyword can be repeated multiple
  times to list all AKAs given by the remote system (one per keyword).

  Syntax: AKA <zone:net/node[.point][@domain]>
  Examples: AKA 2:240/1661@fidonet
            AKA 2:240/1661
            AKA 10:100/1000.1@othernet


Baud

  Data transfer rate of connection in bps. For IP based connections
  the transfer rate is usually stated as 115200.

  Syntax: Baud <line rate>
  Example: Baud 14400


Time

  Time limit for file request. This can be also used to indicate the
  time left until some scheduled task would block file request
  processing.  If there aren't any time constraints the time limit is
  stated as -1.

  Syntax: Time <minutes>
  Example: Time -1


RequestList

  Filepath of the list containing the requested files. This is the
  .REQ file sent by the calling system. The mailer should make sure
  that the filepath is unique to prevent any problems in a multi
  line environment.

  Syntax: RequestList <filepath>
  Examples: RequestList C:\Inbound\011801d0.req
            RequestList /fido/inbound/011801d0.req

  The syntax of the list should follow FTS-0006. A brief refresher:
  Each line lists one filename or search pattern, and can include an
  optional password. Lines end with a CR (Carriage Return, ASCII
  0x0D). 

  Line syntax: <filename or pattern>[<space>!<password>]

  There is no specification of search pattern and wildcard characters,
  which must be supported. Most file request processors support simple
  wildcard characters like '*' for search pattern, e.g. <name>.*. Some
  also process more sophisticated search expressions.

  For interoperability reasons the file request processor should also
  accept lines ending with LF (Line Feed, ASCII 0x0A) or CR-LF.


ResponseList

  Filepath of the list containing the files to be sent as response to
  the file request. The mailer should make sure that the filepath is
  unique to prevent any problems in a multi line environment.

  Syntax: ResponseList <filepath>
  Examples: ResponseList C:\Outbound\011801d0.rsp
            ResponseList /fido/outbound/011801d0.rsp

  The response list states all the files to be sent using following
  syntax:

  Line syntax: <mode><filepath>

  Each line lists exactly one filepath preceded by a mode identifier.
  The line end is not specified, and could be CR Carriage Return,
  ASCII 0x0D), LF (Line Feed, ASCII 0x0A) or CR-LF. Therefore the
  file request processor should use the OS specific line termination.
  For interoperability reasons the mailer should support all line end
  variations.

  The mode identifier is a single character defining how a file has to
  be processed by the mailer:

  =   send file, and erase it after successful transmission
  +   send file
  -   send file, and erase it afterwards in any case

  Typically, files are marked with '+', since they shouldn't be 
  deleted in the system's file base. If the file request processor
  creates a netmail packet or simple text message for feedback
  additionally, those files could be marked with a "=" to have them
  deleted automatically after transmission.


RemoteStatus

  The remote status indicates if the session with the calling system
  is protected or unprotected, i.e. secured by a session password.

  Syntax: RemoteStatus <PROTECTED|UNPROTECTED>
  Example: RemoteStatus UNPROTECTED


SystemStatus

  The system status states if the calling system is listed or not
  listed in any nodelist.

  Syntax: SystemStatus <LISTED|UNLISTED>
  Example: SystemStatus LISTED


2.5 Optional Keywords
---------------------

The following keywords are optional and provide additional information:


Mailer Session
--------------

CallerID

  Caller ID of the calling system. For IP based connections the IP
  address is stated. There is no syntax specified for the ID itself.

  Syntax: CallerID <ID>
  Examples: CallerID +496033921015
            CallerID 123.45.67.89
            CallerID 2001:DB8:F1D0::2:240:9999


OurAKA

  FTS address of the called system. If the mailer performs AKA
  matching it's the AKA which was called by the remote system.

  Syntax: OurAKA <zone:net/node[.point][@domain]>
  Example: OurAKA 2:240/1661@fidonet


SessionType

  The session protocol used in the current session with the calling
  system. Protocols are EMSI, FTSC0001, WAZOO, JANUS, HYDRA or the
  special case OTHER, if none of the protocols listed before is used.

  Syntax: SessionType <protocol>
  Example: SessionType EMSI


SessionProtocoll

  The transfer protocol used in the current session with the calling
  system, e.g. ZAP, ZMO or XMA.

  This keyword includes a spelling error and is defined this way in 
  FSC-0086 unfortunately. We recommend that the file request processor
  should support the bad and the correct spelling.

  Syntax: SessionProtocoll <protocol>
  Example: SessionProtocoll ZAP


Password

  Password of the current session with the calling system in case of
  a protected session.

  Syntax: Password <password>
  Example: Password secret


Line Settings
-------------

DTE

  Current DTE rate between PC and modem in bps.

  Syntax: DTE <rate>
  Example: DTE 57600


PORT

  COM port in case FOSSIL is used. The valid port range is 1-8.

  Syntax: PORT <port number>
  Example: PORT 2


Remote System
-------------

These optional keywords state details of the remote system when that
information is provided by the session protocol. 


Site

  Site information of calling system.

  Syntax: Site <info>
  Example: Site My little BBS


Location

  Location and/or ZIP code of calling system.

  Syntax: Location <town and/or ZIP>
  Example: Location Butzbach


Phone

  Phone number of the calling system. An unpublished number is
  indicated by the character string "-Unpublished-". The format of
  the phone number is:

   <country code>-<city code>-<number>

  The country code is the country calling code without any leading
  zeros or '+'. The city code shouldn't have any leading zeros either.

  Syntax: Phone <phone number>
  Examples: Phone 49-6033-921015
            Phone -Unpublished-


Mailer

  Mailer of the calling system.

  Syntax: Mailer <id>
  Example: Mailer Foozle


MailerCode

  Product code of the calling system's mailer. The code is in
  hexadecimal format (lower or upper case) and can be an 8 bit (old
  code format) or a 16 bit (new code format) value.

  Syntax: MailerCode <id>
  Example: MailerCode 66


SerialNumber

  Serial number of calling system's mailer. The common format is:

    <name><space><version>/<serial number>

  Syntax: SerialNumber <id>
  Example: SerialNumber MyMailer 1.23/123456


Version

  Version of calling system's mailer.

  Syntax: Version <id>
  Example: Version 2


Revision

  Revision of calling system's mailer.

  Syntax: Revision <id>
  Example: Revision 34


TRANX

  Tranx, i.e. local time of calling system. The time is encoded as
  Unix time stamp (32 bit, seconds since 1970-01-01 00:00:00 UTC) and
  formatted as hexadecimal string with 8 digits. The hexadecimal
  digits can be in lower or upper case.

  Syntax: TRANX <time stamp>
  Example: TRANX 5a326682

  The 32 bit time stamp will overflow in 2038. We haven't seen any
  implemented solutions for that yet, so we recommend to support
  also a 64 bit time stamp (string with 16 hex digits) while allowing
  leading zeros to be omitted.


A. References
-------------

    [FTA-1006]
           Keywords to indicate requirement levels, Fidonet Technical
           Standards Committee administrative. FTA-1006.

    [FSC-0086]
           Standard Request Information File (SRIF)
           Gordian Schuermann & Mirko Mucko  

    [FTS-0006]
           YOOHOO and YOOHOO/2U2
           Vince Perriello


B. History
----------
    Rev. 1, 2017-12-13: First release.

ciao,
Markus

--- 
 * Origin: *** theca tabellaria *** (2:240/1661)