; SRE-FILTER support file -- specifying virtual directories. 3/97
;
; I) Introduction               ---------------------
;
;    Virtual directories are used to allow access to files not in a default directory.
;    The typical use is to allow requests for documents to be in a subdirectory
;    NOT under the "GoServe data directory".
;    Virtual files can also be for several other cases, including:
;           specifying the location of a  cgi-bin script
;           specifying the location of an sre-filter add-on
;           specifying where an uploaded file should be placed
;    Lastly, for some cases, virtual directories can be used to allow server
;    mediated access to files on other (remote) servers.
;
; II) Basic structure of entries   ----------------
;
; Each line in this file  should have the following structure:
;     host_nickname//  SEL_fragment  TARGET  limitation_list , username:password
; where:
;   * host_nickname// is optional
;   * SEL_fragment is the "beginning portion" of a request selector
;   * TARGET can be a (local) fully qualified directory or a
;                    (remote) fully specified URL
;   * the [optional] limitation_list is used to limit the applicability of the entry.
;     If present, it should be a spaced  delimited list. It's use is described below.
;   * the [optional] username:password is ONLY used for remote (http://) directories
;
; III) How virtual directories work   ---------------
;
;   The SEL_fragment is compared to the beginning of the request selector (the
;   selector).  If an "abbreviation" match occurs, the
;   "fragment" is removed from the "request selector"
;   and replaced with either the (local) target "directory" OR the
;   (remote) target "URL".  The limitation_list (if present) is used to control
;   which entries are used, based on whether the request is asking for a document,
;   a server side program, or an upload (see section V below for details).
;   If this is confusing, the examples at the bottom of this document should help.
;
;                              
; IV) General Notes                             ------------------
;
;   * If  no match is found, a "default directory" is used.  In the typical case
;     of a document request on a single host server, the default directory is the
;     goserve data directory.
;
;   * The limitation list can be used to limit the "scope" of the entry.
;     In particular, the "default directory"  must match  one of the entries
;     in the limitation list.  If there is no limitation_list, the entry will
;     be used for all requests.
;
;   *  An asterisk (*) at the end of  directory name means "allow access to subdirectories".
;
;   *  Leading and trailing slashes in the SEL_fragment are ignored, and
;      / and \ are treated equivalently.  Similarly, trailing slashes in
;      the TARGET directory are ignored.
;      Thus, the following are all equivalent:
;          foobar1/   d:\foobar\*
;          foobar1    d:\foobar*
;          \foobar1\  d:\foobar*
;
;   *  If a Drive is not specified in the TARGET (local) directory, the drive that
;      SRE-filter is installed on will be used.
;
;   *   WARNING: The use of "REMOTE urls" is ONLY supported for document requests.
;             It is NOT supported for "server side include" files, such
;             as specified in the INCLUDE and INTERPRET keyphrases. Nor is it
;             supported for server side programs, or upload, requests.
;
;   * CAUTION:  The NO_VIRTUAL permission (in ALL_FILE.CTL) suppresses
;               the use of VIRTUAL directories. That is, when a selector
;               matches an ALL_FILE.CTL entry that contains a NO_VIRTUAL
;               permssion, the information in this file will NOT be examined!
;
;
; V) Using the limitation_list   ----------
;
;   The limitation_list is used to limit the applicability of a virtual directory
;   entry. For example, you may wish to have some virtual directories apply only
;   to document requests, and some only to upload requests. 
;   The limitation_list (if present) should contain any mixture of the following
;   special keywords:  !UPLOAD, !CGI-BIN, !ADDONS, and !HTML. 
;        !HTML    --- use this entry for document requests
;        !CGI-BIN --- use this entry for cgi-bin requests
;        !ADDONS  --- use this entry for sre-filter addons
;        !UPLOAD  --- use this entry for file uploads
;   Note that you can contain more then one entry in the "space delimited"
;   limitation list.  Including all four entries is the same as not having
;   a limitation list: the entry will be used for all requests.
;
;   For example:
;      scdemo d:\netdata\macros\scdemo !cgi-bin
;      scdemo d:\netdata\html\scdemo   !html
;   The first entry will be used when a request for a cgi-bin script arrives
;        (i.e.; scdemo/cgi-bin/scinit.cmd
;   The second will be used for document requests  
;        (i.e.; scdemo/foo1.htm)
;
;
; VI) Specifying remote "target urls"   -------------
;
;    i) the http:// MUST be present (otherwise SRE-Filter assumes you
;        are referring to a local directory name)
;    ii) conversion of  / does NOT occur for these entries
;   iii) the trailing * option is supported
;    iv) This is NOT a redirect! Rather, SRE-Filter will retrieve the file
;        represented by this URL (on a remote server), strip out the
;        response headers, and treat it as if it came from a local directory.
;    vi) If you specify a username & password (after a comma), a BASIC authorization
;        request header will be added with this username & password. 
;        Otherwise, the client's username & password is used (if it is available)
;
; VII)  Match precedence      ---------------
;  Unlike most other SRE-Filter files, match precedence for virtual directories
;  is based on "abbreviation" matching, not "best matching".  That is,
;  * wildcards should not be in the SEL_FRAGMENT.  Instead, SRE-Filter simply
;  uses the longest SEL_FRAGMENT that is an "abbreviation" for the request
;  selector.
;
;
; VIII) EXAMPLES --------------------------
;
; LOCAL/PROJECTS     D:\WORK\PROJECTS*
;    If a selector of: /LOCAL/PROJECTS/BOB/PLANE.HTM is recieved, the file
;    returned will be D:\WORK\PROJECTS\BOB\PLANE.HTM.
;
;    Note: If the * is removed, /LOCAL/PROJECTS/BOB/PLANE.HTM would generate
;       a "no access allowed" error (since access to subdirectory BOB, 
;        under WORK\PROJECTS, would not be allowed).
;
; Example of "no subdirectory allowed access"
;    STATES   D:\USA\MAINE
;    .. a selector of STATES/AG.HTM would be valid (and would
;       return D:\USA\MAINE\AG.HTM)
;
; Example of a remote target URL:
;    SERVER2 http://pc2.myorg.net/support1/
;    .. a selector of SERVER2/CANADA.HTM will cause SRE-Filter to request
;    /support1/canada.htm from pc2.myorg.net
;
;  Example of host-specific entry:
;     SWEETSHOP//  CANDY   E:\STORE1\PRODUCTS\CANDY\*
;      ... requests, to hosts with host_nickname of SWEETSHOP, that have
;      selectors beginning with CANDY refer to files in
;      E:\STORE1\PRODUCTS\CANDY (and it's subdirectories).
;
;  Example of a limitation list:
;           ACTION2 e:\programs\task1  !addons
;    The !addons signals that the ACTION2 "virtual directory" will only
;    be used for requests for sre-filter add-ons.
;      For example:
;      /action2/getafile?dir=foodir1
;         E:\programs\task1\GETAFILE.CMD would be executed (as an SRE-Filter add-on)
;      /action2/gogo.htm
;         D:\www\action2\gogo.htm would be returned (assuming that the GoServe data
;        directory is D:\www)
;  
; Some additional examples:
;
; Temp on C, but NO subdirectory access
; CTEMP C:\temp
;
; D:\work, with subdirectory access allowed.
;D\work D:\WORK\*
;
; Get from the EXPORT directory (and directories underneath EXPORT)
; on the server at www.ours.org
;SITE2 http://www.ours.org/export/*
;
; the D:\project1 directory (and subdirectories) contain html documents, and
; sre-filter add-on procedures.
; project1   d:\project1*  !HTML !ADDONS
;
; Remote request to a server, using your server's username:password
; special\  http://server2.hissite.org/grate/stuff/* , specialask:ernie
; ---- End of comments
