The CoffeeMud Web Server:
The CoffeeMud Web Server is a simple, extensible web server that runs as part of CoffeeMud; it uses HTTP 1.0 to communicate with a web browser. In addition to being able to serve standard HTML web pages, it allows mime-types to be specified for any file extension; it also supports a simple server-processed form of HTML called CMVP (Coffee MUD Virtual Pages) - this allows the server to insert information into the page before sending it to the browser. It is NOT intended to be a full-blown web server! This document assumes you have some familiarty with HTTP, mime types, and stuff like that.

How to Connect:
By default, the public web site listens on port 27744 and the administrative web site on port 27777.  To browse the default public web site, just open up the following URL in your browser:

http://localhost:27744/

To connect to the administrative web site, use the following URL:

http://localhost:27777/

What it does and doesn't do:
It only supports GET, urlencoded POST and HEAD requests (I think HEAD is HTTP 1.1, but it's supported anyway).  It does not cache.

Security:
In the default CoffeeMud installation, the server named admin may be bound to 127.0.0.1 (localhost) - this means it will not accept external connections (see below).
The servers will not permit access to a directory or file outside their base directory tree (which includes mounted virtual directories, see below); attempts will generate a log message and return a HTTP 401.

Configuration:
The default installation of CoffeeMud has two inbuilt web servers, named 'pub' and 'admin'. The web servers are enabled with the line 'RUNWEBSERVERS=true' in 'coffeemud.ini'; any other value or the abscence of this line will cause the web servers not to be loaded.

INI files for the web servers live in the 'web/' directory off the CoffeeMud root; by default, all pages to be served go in web/(servername)/, though this can be overridden. Options are placed in either 'web/common.ini' or 'web/(servername).ini'; an option in the latter will override one in common. The options are:

• PORT=xx : [REQUIRED] (e.g. PORT=80) Sets the port number the web server will listen for HTTP requests on; this cannot be the same port as the main MUD server or another web servers. Identical to MUD server usage. Normally this would go in web/(servername).ini.
• BACKLOG=xx : (e.g. BACKLOG=10) Sets the number of requests that can be queued by the internal TCP/IP stack. Identical to MUD server usage.
• BIND=addr : (e.g. BIND=127.0.0.1) Causes the server to be bound to a specific address; this is useful on multi-homed machines or if you wish to prevent public access to the pages. Identical to MUD server usage.
  The Admin server should be bound to localhost (or 127.0.0.1) unless you really know what you're doing...
• DEFAULTFILE=filename : [REQUIRED] (e.g. DEFAULTFILE=index.html) Sets the default filename to be appended if none is specified in the request (or the request refers to a directory - in which case the browser will get a 401 Unauthorized rather than a 404 Not Found if this file doesn't exist).
• VIRTUALPAGEEXTENSION=.xxxx : [REQUIRED] (e.g. VIRTUALPAGEEXTENSION=CMVP) Allows you to change the file extension for server-processed files to whatever takes your fancy. Note that the leading dot is required; you should set MIME.xxxx=text/html, unless you're being clever and serving server-processed plaintext or something. At the moment, the web server only supports one VIRTUALPAGEEXTENSION.
• MIME.xxxx=.yyyy/zzzz : [A GOOD IDEA TO SPECIFY!] (e.g. MIME.HTML=text/html, MIME.JPEG=image/jpg) Allows you to specify a mime type for file extension xxxx; some useful mime types include text/html, text/plain, image/gif and image/jpg. If no mime type is specified for an extension, it defaults to application/octet-stream - which is to say, raw binary; for this reason, it's usually a good idea to specify at least MIME.HTM=text/html and MIME.HTML=text/html - it's also good manners to specify MIME.CLASS=application/octet-stream if you intend to be running java applets on the web pages. Normally these would be placed in web/common.ini.
• ADMIN= true : allows admin macros to run on this server (see below).
• BASEDIRECTORY=path : allows you to override the web-page directory that this server uses - default is web/(servername). Servers can share base directories.
• TEMPLATEDIRECTORY=path : allows you to override the web-page template directory that this server uses - default is BASEDIRECTORY + .templates. The template directory is where pages such as error.cmvp are placed. Servers can share template directories.

Virtual Directories:
This is a quick-and-dirty directory mounting method; using an operating-system specific method would be preferable. Nevertheless, you can specify MOUNT/virtualdir=physicaldir in a server cfg file; for example, MOUNT/guides=guides creates a virtual directory with access to the player guides.
Now the limitation - URLs that do things like this: /guides/.. won't work; this means you can't link BACK from a virtual directory with a RELATIVE link, unless you rely on the user's browser to preprocess the URL and remove redundancies; instead, specify a path from the root ('/') - e.g., instead of ../index.cmvp specify /index.cmvp.

CoffeeMud Virtual Pages:
Kind of misnamed (these pages in their original, very different incarnation didn't exist at all), this is typically a HTML or plaintext file that is preprocessed by the server before being dispatched to the browser. Preprocessing is a simple search-and-replace; NO ACCOUNT is taken of where the macro appears within the file (ie, macros within comments or quoted strings will be replaced).

Macros are always surrounded by the AT sign (@), and are thus delineated in the page.  Any parameters required for a macro always follow the macro name and a Question Mark (?).  Further parameters are separated by the Ampersand (&) character.  Each parameter may optionally be an equation, where the name is on the left of an equal sign, and its value on the right.  An example of all this in action would be:

@MacroName?PARAMETER&PARM2=VALUE&PARM3@

Macros may be embedded in each other ONLY if the embedded macros are part of the parameters of the host macro, which means they must follow the Question Mark.   Also, for each level of embedding, an extra At sign (@) character is used around the macro.  To avoid confusion, the closing At signs (@) should be separated by spaces.  Here is an example of embedded Macros (in this case, two macros are used for each of two parameters to a first macro (MacroOne):

@MacroOne?@@MacroTwo?PARM@@&@@MacroThree?PARM@@ @

Notice the space before the final At sign (@).  Now, here is an example of double-embedding, where MacroThree is embedded as the parameter to MacroTwo, which is embedded as the parameter to MacroOne:

@MacroOne?@@MacroTwo?@@@MacroThree?PARM@@@ @@ @

Here are the macros defined so far.  Keep in mind the difference between a Macro parameter (things which follow the first Question mark in a macro), and a Request Parameter (data submitted from a <FORM> on a web page, or on the URL line of a GET request).  Macro parms will be abbreviated to MacParm, while Request Parameters will be abbreviated to ReqParm.

Customising the error page:
Simply create a file error.cmvp (or whatever the v.p. extension is) in the template directory of the server; at some point on the page you should use the @HTTPSTATUS@ and @HTTPSTATUSINFO@ macros. Note that the template directory is served as though it were in the specified path - images and stylesheets should therefore go in the server's base directory.

Adding new macros to CMVP:
Create the new .java file in the com/planet_ink/coffee_mud/web/macros directory; all classes in this directory are loaded as macros by default.
The new class should inherit from StdWebMacro in the com.planet_ink.coffee_mud.web package.
The package of the new class should be com.planet_ink.coffee_mud.web.macros; the name() member should return the name of your new macro (it will be capitalised and the @ symbols added by StdWebMacro) - the name doesn't have to match the class name but it is recommended to avoid confusion.
Finally, the runMacro() function returns the String data you wish to insert into the processed output; it takes a single parameter, a reference to the ProcessWebRequest that is calling the macro (you can use .getWebServer() on this parameter to get a reference to the web server, and .getWebServer().getMUD() to get a reference to the main MUD object).
If runMacro() returns null, the string [Error] is used to replace the macro; also note that macros may not return other macros in the processed text unless properly embedded as discussed above.

package com.planet_ink.coffee_mud.web.macros;
import com.planet_ink.coffee_mud.interfaces.*;
import com.planet_ink.coffee_mud.common.*;
import com.planet_ink.coffee_mud.utils.*;

public class HTTPclientIP extends StdWebMacro
{

	public String name() {return "HTTPclientIP";}

	public String runMacro(ExternalHTTPRequests httpReq, String parms)
	{
		return httpReq.getHTTPclientIP();
	}

}

The .getHTTPclientIP() member of ProcessWebRequest essentially just does this:

	return sock.getInetAddress().getHostAddress();

(don't be confused by the name .getHostAddress() - this just returns the dotted quad notation form of the address, whereas .toString() would attempt to do a reverse DNS(?) and return a meaningful name as well)

If your macro is intended to be for the admin server only, you can override the .isAdminMacro() member to return true.