15 Apr 1998: ByClient.RXX :  Using Client Specific Documents.

Abstract:
  ByCLIENT.RXX is an "INTERPRETable" SRE-http addon that simplifies the
  deliver of "client specific" documents to your WWW clients.

Contents:

1.0 Introduction
2.0 Using ByCLIENT.RXX
2.1 A Simple Example
2.2 Syntax of a .USR file
2.3 Specifying IDs
3.0 Miscellaneous Notes
4.0 A sample
                        --------    ----   ---------

1.0) Introduction

ByCLIENT.RXX is an "INTERPRETable" SRE-http addon that simplifies the
delivery of "client specific" documents to your WWW clients.  Using
ByCLIENT.RXX requires creation of special instructions files (.USR files)
that identify which files should be delivered to which clients. After
identifying the client, ByCLIENT will use this .USR file to ascertain
a file to be INCLUDEd in the document.

Identification of clients is based on a number of possible pieces of
information, including: special ByCLIENT cookies, the SRE-http "client
privileges", or the IP namd and address.  The .USR file can freely mix
these different "client identification" mechanisms.


Hint:
    For many purposes, the use of content-negotiation (either server side
    or client side) will be easier (and more efficient) then using this
    BYCLIENT addon. Please see NEGOTIAT.DOC for the details


                        --------    ----   ---------

2.0) Using ByCLIENT.RXX

To use ByCLIENT.RXX, you just need to include

    <!-- INTERPRET FILE ByCLIENT.RXX -->

"SSI keyphrases" in a "requesting document". When this "requesting document" 
is requested by a client,  SRE-http will call (actually, SRE-http will 
read and "interpret") ByCLIENT.RXX. ByCLIENT.RXX will find a .USR
file (with the same name as the "requesting document"), match the
"client" with an "rule" in this .USR file, and INCLUDE the "client
specific document" this rule points to.

Inclusion of these client specific documents is accomplished via a
<!-- #INCLUDE file=docname >  or <!-- #INCLUDE virtual=docname > 
server-side includes (where docname is the "client specific document"
specified in the .USR file).  Typically, these files will contain information
relevant to a subset of clients (say, "intranet" versus "extranet" clients).

In addition to the (unavoidable) task of writing these client specific 
documents, use of ByCLIENT requires creation of .USR files. These .USR
files consist of a series of matching "rules". Each rule contains two sets
of information: the file to use, and the clients for whom this file should
be used.  
   * File to use: The file to use should be specified relative to the
     web space of your server, or relative to the location of the
     "requesting document". 
    
   * Client identification: Clients may be identified via cookies,
     client privileges, or IP address.   
       Cookies: If a BYCLIENT cookie was passed to the server, its value
       will be used as a client-id. 
       Client privileges: Each of the various "client privileges" will
       be used to identify 
       IP address: The IP address (numeric or name) can be used to 
       identify a client -- with wildcards used to specify entire domains.

    Note that a client may be identified several times; say, through
    a BYCLIENT cookie, through several client privileges, and through
    several wild-card'ed domains.  In such cases, the cookie "identification"
    is tried first, followed by the client privileges, followed by
    the IP address.  

As this point, a simple example should help....

                        --------    ----   ---------

2.1) A Simple Example

Let's assume the following URL on your home page:
    <A href="/NEWS.HTM">Today's news? </a>
Let's also assume that /NEWS.HTM points to D:\WWW\NEWS.HTM,
and that D:\WWW\NEWS.HTM contains the following:

   <h2>Local news</h2>
      <!-- INTERPRET FILE ByCLIENT.RXX -->
   <h2> National news </h2>

Thus, the "local news" will be "client specific".

SRE-http will invoke ByCLIENT.RXX, and ByCLIENT.RXX will look for
a file named D:\WWW\NEWS.USR. NEWS.USR should contain "rules" used
to determine what file this client should get. For example:

; ByCLIENT .USR file for /NEWS.HTM
COOKIE: /stories/news1.inc     class1 class2
PRIVILEGE: /stories/news1.inc  priv1 priv2 priv3
PRIVILEGE: /stories/newsA.ink  privas privb
IP: /stories/news1.inc   *.mysite.net *.newsdog.com *.131.51
IP: /stories/newsa.ink   *.hersite.net *.newsdog.com *.31.61
COOKIE: /stories/newsA.ink     classA classB

These rules select between two files: D:\WWW\STORIES\NEWS1.INC and
D:\WWW\STORIES\NEWSA.INK.  Each rule consists of three components:
the "type" of rule, the file, and a space delimited list of client
ids.  Note that lines beginning with a ; are comments.

The actual file "INCLUDED" will depend on the values of the ByCLIENT
cookie, the client privileges, and the client's IP address.  For example:

  *  If BYCLIENT=CLASS2 and the client's IP name is JOHN.MYSITE.NET
        then D:\WWW\STORIES\NEWS1.INC will be used.

  *  If BYCLIENT=CLASS6 and the client has a PRIVB privilege; 
        then D:\WWW\STORIES\NEWSA.INK will be used.

   * If there is no BYCLIENT cookie, and the client's IP name 
     is JOHN.NEWSDOG.COM;
        then D:\WWW\STORIES\NEWS1.INC will be used.

The key to using ByCLIENT is to understand how the .USR file identifies
clients. The next section discusses the syntax of these .USR files.

                        --------    ----   ---------

2.2) Syntax of a .USR file


The .USR file is used to match a client to a filename. This filename
(which is specified using a "selector" style of name) will then be
#INCLUDEd in the requesting document.

When an <!-- INTERPRET ByCLIENT.RXX --> keyphrase is encountered,
ByCLIENT will look in the "requesting documents" directory 
for a file with a .USR extension. If no such file can be found, nothing
is done (i.e; the <!--INTERPRET  ByCLIENT.RXX --> keyphrase is ignored).

NOTE:  You can specify an explicit .USR file to use. For example:
             <!-- INTERPRET ByCLIENT.RXX  buttons/helplink.usr --> 
      (see this section's notes for further details).

Note:
  
  *  To specify an explicit .USR file, place its name after the 
     ByCLIENT.RXX.  For example:
             <!-- INTERPRET ByCLIENT.RXX /order/form1.usr --> 
     This can be  quite useful if you have a commonly used file
     (say, a button bar), or if you want to include several files 
     (say, several different tables in an otherwise generic document).

     Note that the location of this "explicit" .USR file is
     either relative to the "requested document's directory" (if the
     filename does NOT begin with a /). When this filename starts with a
     /, it is interpreted using the standard SRE-http selector rules 
     (i.e.; using the data directory and virtual directories).
      
The .USR file is an ascii (text) file.  Each line of the .USR file 
is a "rule" that is used to match clients to INCLUDEable files.

The syntax of these rules is:
   type  filename   id1 ... idn
where
  type:  The type of "client ID". Three types are recognized:
         * COOKIE: The value of the "ByCLIENT" cookie (if one exists).
         * PRIVILEGE: The values of the SRE-http client privileges
         * IP: IP addresses (either numeric or name)

  filename: The "selector" style filename of the file to be #INCLUDEd.
            This file is assumed to be either
               a) relative to the requesting document's directory, or 
               b) relative to the root of the web tree, or in a virtual
                  directory
           In particular, if the filename does NOT start with a /, then
           a is used. If the filename DOES start with a /, then b is used.
           In other words:
             foo/bar.1 is equivalent to <!-- #include file="foo/bar.1" -->
           and
             /foo/bar.1 is equivalent to <!-- #include virtual="foo/bar.1" -->

  id1 ..idn : A space delimited list of "client identifiers". The values
              will depend on the type.  Thus, if type=IP, then these "ids"
              should be IP addresses (either name or number). Or, if
              type=COOKIE, then these "ids" should be possible values
              of a ByCLIENT cookie.

In addition to these three rules, lines starting with semi-colons
are treated as comments, and empty lines are ignored.

2.3) Specifying IDs

When looking for a rule with a matching ID, ByCLIENT does the following:

1) Checks for a ByCLIENT cookie (note that the case of ByCLIENT is ignored).
   All COOKIE "rules" are then checked.  The first rule that contains
   an id that matches ByCLIENT will be used, provided that the 
   filename (contained in the rule) exists. 
   If it does not exist, the next COOKIE rule is used.

2) If no matching COOKIE rule can be found, the PRIVILEGE rules are used.
   Since there may be many client privileges, each id is compared against
   all the client privileges -- if a match is found, then the rule
   is used. As with COOKIE rules, if the filename does not exist, the
   next PRIVILEGE rule is used.

3) If no matching PRIVILEGE rule can be found, the IP rules will be checked.
   IP ids can either by numeric (i.e.; 121.55.12.5) or name (i.e.; 
   JOE.COWS.ORG).  The IP ids can also contain * wildcards.

4) If no matching PRIVILEGE rule can be found, 
   the <!-- INTERPRET ByCLIENT.RXX -->  SSI keyphrase is ignored.


3.0) Misellaneous Notes

  *  Please be aware that within a "type" of rules, rules nearer the
     top of the file are used in precedence to rules that are lower
     in the file. Conversely, COOKIE rules are always used before
     PRIVILEGE (and IP) rules, regardless of where they appear.

  *  There are a number of ways of specifying "cookies".  The easiest
     way is to use a META element in the <HEAD> section of an HTML document
     that is examined before the "requesting document" is loaded.
     For example, you might include:
           <meta http-equiv="Set-Cookie:" content="ByCLIENT=USER_REG">
     on a "registration" page that contains a link to the "requesting
     document" (that is, a link to the document containing the
     <!-- INTERPRET FILE ByCLIENT.RXX -->)

  *  Wildcard characters (the *, several of which may appear) used in IP "ids"
     are used in a standard string-matching fashion. 
     Thus, an id of *.121.55 would match 5.21.121.55 and would match 62.121.55.

  *  Wildcard characters can NOT be used with PRIVILEGE rules, but can
     be used with COOKIE rules.

  *  For a more dynamic form of "client customization", that makes extensive 
     use of cookies, consider the CUSTOMIZ addon. CUSTOMIZ can be on obtained 
     from http://www.srehttp.org/apps/customiz/.
  
  *  Reminder: you can modify client privileges by changing "user"
     entries in the USERS.IN file.  This, however, requires the
     client to login.  Alternatively, the PUBLIC_PRIVS, INHOUSE_PRIVS,
     and INHOUSEIPS. entries allow you to set privileges on a 
     global and on a per-IP-address basis.

  *  It's a good idea to specify a "default" rule as the last entry in a 
     .USR file. For example:
         IP  /stories/news0.htm  *
     will cause /stories/news0.htm to be used for ALL IP addresses.

                        --------    ----   ---------
4) Demo

The following simple sample can be used to demo ByClient.RXX. 
To use this demo:

 a)With your favorite text editor, cut out the code and create 
   the indicated files, 
 b)Request /ByClient.sht
   or, to first set a cookie, 
 c) request /ByClien2.Sht?cookie_value
      (where cookie_value could be COOK1 or COOK2)
    and then request /ByClient.sht


1) BYCLIENT.SHT (in your GoServe data directory):
                  ------- cut here ---------------
<!DOCTYPE HTML PUBLIC "-//W3 Organization//DTD W3 HTML 2.0//EN">
<html>
<head>
<title>Test ByCLIENT</title>
</head>
<body>
<h1>Test of ByClient</h1>

<!-- This will cause the "client specific" file (BYC.0...BYC.5)
     to be INCLUDEd -->

Welcome.<p>
<!-- interpret file $ byclient.rxx  -->

</body>
</html>
                 ------- cut here ---------------

2) ByCLIEN2.SHT (in your goserve data directory)
                  ------- cut here ---------------
<html><head>
<title>SEt ByClient Cookie </title>
<meta http-equiv="Set-cookie:" content="ByClient=<!-- option 1-->" >
</head><body>
<h1>Set ByClient Cookie</h1>
<p> Your ByClient cookie has been set to <!-- option 1-->
<hr>
<b>Note:</b> To set client, use a selector of:
            <tt>/byclien2.htm?cookie_value</tt>
</body></html>
                  ------- cut here ---------------

3)ByCLIENT.USR -- same directory as byclient.sht
                  ------- cut here ---------------
;sample .USR file for ByClient
ip byc.1 127.*.*
cookie byc.2 cook2 owner
cookie byc.3 cook23
priv byc.4   byclientp
priv byc.5   superuser
ip byc.0 *
                  ------- cut here ---------------

4) Create Byc.0, byc.1, to byc.5 in the same directory as 
   byclient.sht.
   For exampe, simple one line files can be used:
BYC.0  :  This is the default message
BYC.1  :  This is the message for loopback clients (on 127.*.*)
BYC.2  :  Message for clients with ByClient cookie of <b>cook2</b> or <b>owner</b>
BYC.3  :  Message for clients with ByClient cookie of <b>cook23</b> 
BYC.4  :  Message for clients with a <b>byclientp</b> privilege
BYC.5  :  Message for <b>SUPERUSER</b>s

Reminder: the above entries represent 6 seperate files!

                        --------    ----   ---------

.End of document.