Exporting URLs in CL-HTTP

HTTP:EXPORT-URL is the primary method that exports URLs, and thereby, makes them accessible via the HTTP server. HTTP:EXPORT-URL takes arguments URL, EXPORT-TYPE. The URL argument is either a string or an interned URL. EXPORT-TYPE is the method to use in exporting URL. EXPORT-TYPE also determines a set of additional arguments which are explained below. HTTP:DEFINE-URL-EXPORTS allows many URLs to be exported at once. HTTP:UNEXPORT-URL makes an exported URL inaccessible via the HTTP server.

1. Basic Export Types: These involve making the contents of a file accessible via a URL. These types require URLs that are objects (i.e., have a name and extension).
   • Text
     • :HTML-FILE (&key pathname)
     • :TEXT-FILE (&key pathname)
     • :RTF-FILE (&key pathname)
   • Images
     • :GIF-IMAGE (&key pathname)
     • :JPEG-IMAGE (&key pathname)
     • :X-BITMAP-IMAGE (&key pathname)
     • :PICT-IMAGE (&key pathname)
     • :TIFF-IMAGE (&key pathname)
   • Audio
     • :BASIC-AUDIO (&key pathname)
     • :AIFF-AUDIO (&key pathname)
     • :WAV-AUDIO (&key pathname)
   • Video
     • :MPEG-VIDEO (&key pathname)
     • :QUICKTIME-VIDEO (&key pathname)
   • Other
     • :PDF-FILE (&key pathname)
     • :POSTSCRIPT-FILE (&key pathname)
     • :BINHEX-FILE (&key pathname)
     • :STUFFIT-FILE (&key pathname)
     • :COMPRESSED-FILE (&key pathname)
     • :MAC-BINARY-FILE (&key pathname)
     • :WORD-FILE (&key pathname)
     • :POWER-POINT-FILE (&key pathname)
     • :EXCEL-FILE (&key pathname)

2. Directory Export Types: These export all the files in a directory or a directory hierarchy when RECURSIVE-P is non-null. The most general export type, :DIRECTORY, exports all files whose resource type is known. Others export a specific content type, and ignore other file types.

   When HTTP:*AUTO-EXPORT* is non-null, new files are automatically exported when they are scoped by one of these directory export types. Auto-export occurs on demand for the GET and HEAD methods of HTTP.

   Note that the presence in file or directory names of escaped characters (see HTTP:*ESCAPED-CHARACTERS*) will lead to inconsistent results, and possibly errors. Space and question mark are examples.

   • :DIRECTORY (&key pathname recursive-p)
   • :HTML-DIRECTORY (&key pathname recursive-p)
   • :TEXT-DIRECTORY (&key pathname recursive-p)
   • :LISP-DIRECTORY (&key pathname recursive-p)
   • :IMAGE-DIRECTORY (&key pathname recursive-p)
   • :AUDIO-DIRECTORY (&key pathname recursive-p)
   • :VIDEO-DIRECTORY (&key pathname recursive-p)
   • :APPLICATION-DIRECTORY (&key pathname recursive-p)

3. Redirect Export Types: These inform the client to look elsewhere for a URL. They work for the GET and HEAD operations. The exported URL can be either an HTTP object or an HTTP path.
   • :REDIRECT (&key alternate-urls pathname)
   • :TEMPORARY-REDIRECT (&key alternate-urls pathname)

4. Search Export Types: These involve performing searches using the search index or map search facilities in HTTP. Search URLs must end with ? so that the system can composed the right combination of classes. In all cases, the response function must compute the answer and return HTML over the http stream to the client.

   • General Purpose Searches
     • :SEARCH (&key response-function search-database) This exports a URL that performs searches by calling RESPONSE-FUNCTION with the arguments URL and STREAM. The search database and search parameters are cached on the URL and accessible via URL:SEARCH-DATABASE and URL:SEARCH-KEYS.

   • Image Searches: These allow the client's user to click on images and invoke a response from the server. These URL are both objects and searchable. When they are requested without the ? suffix, the contents of their associate image file is returned. When the ? suffix appears, their RESPONSE-FUNCTION is called on the arguments URL and STREAM. See the macro HTTP:WITH-IMAGE-COORDINATES automatically binds the X and Y coordinates.
     • :GIF-IMAGE (&key pathname response-function search-database)
     • :JPEG-IMAGE (&key pathname response-function search-database)
     • :X-BITMAP-IMAGE (&key pathname response-function search-database)

5. Computed URLs: These compute responses returned to clients.

   • :HTML-COMPUTED (&key response-function pathname) RESPONSE-FUNCTION is called with the arguments URL and STREAM and is responsible for returning HTML to the client. :html-computed has an optional pathname so that the computation may reference a file, if necessary.

   • :HTML-FORM (&key response-function pathname server) :html-form returns the contents of PATHNAME when it is requested via GET. When there is a POST, its RESPONSE-FUNCTION is called with URL, STREAM, and FORM-ALIST. FORM-ALIST is an alist of (QUERY RAW-VALUE) for all the queries in the form that the client returns. QUERY is a keyword. When a client returns multiple raw-values for a QUERY, these are aggregated into a list of the values associated with the query in a single, order-preserving entry.

   • :HTML-COMPUTED-FORM (&key form-function response-function server) :HTML-COMPUTED-FORM is a cross between :HTML-COMPUTED and :HTML-FORM that provides FORM-FUNCTION to generate html just like :HTML-COMPUTED and RESPONSE-FUNCTION to handle the post method when form values are returned. FORM-FUNCTION is called with the arguments URL and STREAM and is responsible for returning HTML to the client. response-function takes the same arguments as :HTML-FORM.

6. Expiration: The expiration time for a url is issued as an EXPIRES header so that proxy servers can determine when they need to refresh their cache. Expiration is controlled by providing the :EXPIRATION keyword argument when exporting any URL. If expiration is not provided, the default is no expiration date. The :EXPIRATION keyword takes one argument, which is either keyword or a list of (keyword &rest arguments). The following expiration arguments are handled:
   • :NO-EXPIRATION-HEADER -- No EXPIREs header is issued.
   • :NEVER -- EXPIRES header indicates one year from now.
   • (:TIME universal-time) -- EXPIRES header indicates an universal-time.
   • (:INTERVAL universal-time) -- EXPIRES header indicates an now + universal-time.
   • (:FUNCTION ) -- EXPIRES header indicates universal time computed by applying to URL. should return a universal for use in the EXPIRES header or NIL, in which case no EXPIRES header is issued.

7. Subnet Security: Global and local mechanisms are available for controlling subnet access based on IP address.

   • HTTP:DEFINE-SECURE-SUBNETS restricts access globally to the server.

   • The :SECURE-SUBNETS keyword is supported by every URL export type. It takes an optional list of IP addresses, which when specified, allows only hosts at these address to access the URLS denoted by the export operation. Secure subnets are specified as a list of IP addresses, where zero is a wild card. So, for example '("128.52.0.0") matches all the AI lab subnets.

8. Documentation: Keywords and a descriptive string can be attached to URLs at export time. For directory exports, note that these arguments apply to ALL URLs exported during the directory walk.
   • :KEYWORDS -- A list of keywords characterizing the URL.
   • :DOCUMENTATION -- A string describing the URL.

9. Portable Exports: The #U reader macro merges a partial URL specification against the default for the local host. Use this when you be able to load the same exports file on different hosts.

10. Defining Static Export Types: New static export types for data stored in files can be defined with DEFINE-URL-EXPORT-TYPE.