CoffeeMud Web Server

• Introduction
• How to Connect
• Features
• Security
• Configuration
• Virtual Directories
• CoffeeMud Virtual Pages
• Customizing the error pages
• Adding new macros to CMVP
• Using Javascript in your pages
• Servlet interfaces
• WebSockets 

  The CoffeeMud Web Server is a simple, extensible web server that runs as part of CoffeeMud; it uses HTTP 1.1 to communicate with a web browser. In addition to being able to serve standard HTML web pages, it also supports a  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. This document assumes you have some familiarty with HTTP, mime types, and stuff like that.

How to Connect

By default, the public (pub) web site listens on ports 80 and 27744 and the administrative (admin) 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/

Features

It supports GET, urlencoded and multipart POST requests, and HEAD requests.  It supports custom servlets, websocks, cookies, sessions, SSL, gzip and deflate encodings, pipelining, etag support, ranged requests, async IO (fast!), mapping mime types to java converter and filter classes, file caching, and more.  It supports numerous coded web macros, as well as inline server-side Javascripts to create custom pages.  It does not make coffee, but it does make CoffeeMud better. :)

Security

The web server uses explicitly mounted directories to control access to your CoffeeMud filesystem (CMFS).  You can mount more directories or remove existing ones by changing the MOUNT list in the configuration files (see below).   The default installation runs one of the two web servers with an "ADMIN=true" flag in its configuration, allowing it to access the more powerful CoffeeMud macros.  The web server also supports SSL (https).  However, this is not turned on by default, since it requires access to a special SSL web certificate from a respected certification agency, such as Verisign.  To learn more about setting this up, see the SSLPORT entry and the information under SSL CONFIGURATION in the common.ini configuration file.  Lastly, the configuration files have a BIND entry that can be used to restrict connections to your administration server, but is not set by default.

Configuration

The default installation of CoffeeMud has two inbuilt web servers, named 'pub' and 'admin'. The web servers are enabled with the line 'RUNWEBSERVERS=pub,admin' in 'coffeemud.ini'; absence 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.  This means that some configuration options are in web/pub.ini for the "pub" server, web/admin.ini for the "admin" server, and web/common.ini for Both.

The configuration options are:

• PORT=xx : [REQUIRED] (e.g. PORT=80) (e.g. PORT=80,27744)
  SSLPORT=xx (e.g. SSLPORT=443)
  

  Sets the port number the web server will listen for HTTP and HTTPS requests on; this cannot be the same port as the main MUD server or another web servers. This list may be comma delimited to start more than one instance on different ports. Normally this would go in pub.ini and admin.ini.

• DEBUGFLAG=xx : (e.g. DEBUGFLAG=off)

  An alternative way to turn on debugging messages in the web server.  The more appropriate way is the DEBUG entry in coffeemud.ini.  Values here include ON, OFF, FILE, or BOTH.

• 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) in admin.ini unless you really know what you're doing...

• ADMINEMAIL=email address: 
  The administrators email address, for informational purposes only.
  
• DEFAULTPAGE=filename : [REQUIRED] (e.g. DEFAULTFILE=index.cmvp)

  Sets the default filename to be appended if none is specified in the request.  This is in common.ini.

• MOUNT*=/web/path
  This is where you specify how requested hosts and contexts will map to actual directories on your local hard drive.  The way it works is that you specify the word MOUNT followed by a forward slash character / and the optional host name and optional port, and the context, then set that equal to the coffeemud directory path that the given context should map to.  Be sure to end your hard drive path with a path separator /.  The example MOUNT/mydomain.com:80/remote=/web/pub maps the context /remote on the host
  "mydomain.com" on port 80 to the CoffeeMud local path "/web/pub" The example MOUNT/=/web/admin maps the root context / to the relative path "root\\" for all hosts and ports.
  
• SSLKEYSTOREPATH=path/to/keystore.jks (e.g. SSLKEYSTOREPATH=keys/keystore.jks)
  SSLKEYSTOREPASSWORD=keystore file password (e.g. SSLKEYSTOREPASSWORD=mypassphrase)
  SSLKEYSTORETYPE=JKS (are there other useful values for this?)
  SSLKEYMANAGERENCODING=SunX509 (are there other useful values for this?)
  

  Allows you to turn on support for SSLv3 via a java keystore file (SSLKEYSTOREPATH), but you can specify any key file format that java supports, so long as you also specify its type (SSLKEYSTORETYPE).  If the keystore/file has a password, specify it also (SSLKEYSTOREPASSWORD). If any of this stuff is invalid, the web server will not attempt to listen on your SSL ports.  These are normally in common.ini

• FILECACHEEXPIREMS=milliseconds (e.g. FILECACHEEXPIREMS=300000)
  FILECACHEMAXBYTES=#bytes (e.g. FILECACHEMAXBYTES=65535)
  FILECACHEMAXFILEBYTES=#bytes (e.g. FILECACHEMAXFILEBYTES=8192)
  FILECOMPMAXBYTES=#bytes (e.g. FILECOMPMAXBYTES=16485760)

  The data for your web site can be cached in memory for better performance.  To tune this feature, you can specify the amount of time a cache entry lives in memory (FILECACHEEXPIREMS), how much TOTAL file data will be stored in the cache before it starts forcing entries out of the cache to make more room (FILECACHEMAXBYTES), and the maximum size of any one file stored in the cache (FILECACHEMAXFILEBYTES). The maximum size of any file that can be compressed is  FILECOMPMAXBYTES. To turn any of these off entirely, specify a value of 0.  If you have lots of allocated java memory, however, making those numbers larger will help performance.  These are also in common.ini.

• REQUESTMAXBODYBYTES=#bytes (e.g. REQUESTMAXBODYBYTES=2097152)
  REQUESTMAXIDLEMS=milliseconds (e.g. REQUESTMAXIDLEMS=30000)
  REQUESTLINEBUFBYTES=#bytes (e.g. REQUESTLINEBUFBYTES=65535)
  REQUESTMAXALIVESECS=seconds (e.g. REQUESTMAXALIVESECS=15)
  REQUESTMAXPERCONN=#requests (e.g. REQUESTMAXPERCONN=20)
  
  This is some fine tuning regarding constraints on http requests.  You can specify the maximum size of any request body (REQUESTMAXBODYBYTES), the number of milliseconds a connection can sit idle between requests (REQUESTMAXIDLEMS), The maximum size of any one line of request data, such individual headers, url length, etc (REQUESTLINEBUFBYTES), the longest amount of time a connection can hang around sending requests to the web server and receiving data (REQUESTMAXALIVESECS), and the maximum number of requests that can be made on a single connection (REQUESTMAXPERCONN). 
  
  All of these are normally defined in common.ini, except for REQUESTMAXALIVESECS, which is defined in pub.ini and admin.ini by default.
  
  
• CORETHREADPOOLSIZE=#threads (e.g. CORETHREADPOOLSIZE=1)
  MAXTHREADS=#threads (e.g. MAXTHREADS=10)
  MAXTHREADIDLEMILLIS=milliseconds (e.g. MAXTHREADIDLEMILLIS=60000)
  MAXTHREADQUEUESIZE=#tasks (e.g. MAXTHREADQUEUESIZE=500)
  MAXTHREADTIMEOUTSECS=seconds (e.g. MAXTHREADTIMEOUTSECS=30)
  
  Now for the really geeky stuff.  The web server will try to process as many requests at the same time as it can by spawning threads when it needs to.  You can tweek this process right here.  You can specify the minimum number of threads to keep hanging around waiting
  to process requests (CORETHREADPOOLSIZE), as well as the absolute maximum number (MAXTHREADS). You can also specify the amount of time a thread goes unused before it is shut down (MAXTHREADIDLEMILLIS), the maximum number of tasks that can be queued up waiting for thread time (MAXTHREADQUEUESIZE), and the absolute maximum amount of time a thread is allowed to
  work on any one task (MAXTHREADTIMEOUTSECS).
  
  All of these are normally defined in common.ini, except for MAXTHREADTIMEOUTSECS, which is defined in pub.ini and admin.ini by default.
  
  
• ADMIN=true/false

  This allows admin macros to run on this server or not (see below).  This is always in admin.ini, for obvious reasons.

• MIME.*=xx
  Defines a new mime type.  For example, MIME.php=application/php
  
• MIMECONVERT.*=javaclass
  For the Java programmers, there is an interface available at com.planet_ink.coffee_web.interfaces.HTTPOutputConverter for creating classes that transform data from a specific mime type by processing it. Since it only supports the mime types hard coded into com/planet_ink/coffee_web/http/MIMEType.java. this is of limited usefulness -- still, you can do cool things make make custom http page converters! When you create such a converter, you specify it here by mapping the class to a mime type name by using the word "MIMECONVERT" followed by a period, followed by the mime type name, and then setting that equal to the java class name where your HTTPOutputConverter can be found.  Have as many as you like! Of course, using a mime converter will invalidate any eTag processing, since the whole point is to change the contents of pages from disk. :)
  MIMECONVERT.cwhtml=com.planet_ink.coffee_web.converters.CWHTMLConverter
  MIMECONVERT.cmvp=com.planet_ink.coffee_mud.Libraries.WebMacroCreamer
  
• ERRORPAGE=path/filename (e.g. ERRORPAGE=/web/pub.templates/errorpage.cwhtml)

  When an error or exception is generated, which page is displayed.  This is a LOCAL PATH,  either relative or absolute.  This is normally defined in the pub.ini and admin.ini files.

• FORWARD*=address
  This is where you specify how requested hosts, ports, or contexts will be forwarded to other web servers and ports and contexts. The way it works is that you specify the word FORWARD followed by a forward slash character / and the optional host name and optional port and the context (or just /), and then set that equal to the host name of the remote web server, followed by a colon and the remote port number.  You can specify as many mappings as you like .. coffeewebserver will be pretty smart about  which is the proper one to use for any particular url.
  Remember to escape your colons and backslashes (if you use them)!!  Some examples:
  FORWARD/mydomain.net\:80/contextname=www.google.com\:80
  FORWARD/localhost\:8080/zimmers=www.zimmers.net\:80
  
• CGIMOUNT*=/web/path
  This is where you specify how requested hosts and contexts will map to CoffeeMud paths on your local hard drive containing CGI (Common Gateway Interface) programs that the server is permitted to execute.  Any URL path parts after the mount directory is passed to the cgi-program. The mount path can also be an executeable file name. The way it works is that you specify the word CGIMOUNT followed by a forward slash character / and the optional host name and optional port, and the context, then set that equal to the CoffeeMud path that the given context should map to.  If thepath is a directory, any cgi-programs in it may be executed, and if it is a program file, it will be executed against the referenced path.  The URI context may also contain a "*" character for filtering purposes.  Be sure to end your path with a path separator /.  The example CGIMOUNT/mydomain.com:80/cgi-bin=root\\cgi-bin\\ maps the context /cgi-bin on the host
  "mydomain.com" on port 80 to the relative local path "root\\cgi-bin\\"  The example CGIMOUNT/*.php=cgi-bin\\php-cgi.exe executes the given cgi program against any .php files for
  all hosts and ports.
  
• BROWSEPAGE=path/filename (e.g. BROWSEPAGE=/web/pub.templates/browsepage.cwhtml)

  When a directory is encountered which is permitted to be browsed (see BROWSE below), this is the local path, relative or absolute, of the page to display.  If the page is kept at cwhtml or another Convertable type, then the page will correctly fill in directory entries.

• BROWSE*=xx
  This is where you specify which virtual paths which, after going through mount processing, resolve to directories that you will permit browsing of. Specify the word BROWSE followed by a forward slash character / and the optional host name and optional port, and the context, then  set that equal to anything you like (the value is reserved for future use at this point). The example BROWSE/mydomain.com:80/mysubdir=OK allows the context /mysubdir on the host "mydomain.com" on port 80 to be browsed.  The example BROWSE/=YES allows all directories, all hosts, all ports, to be browseable
  
• ACCESSLOGS=xx : (e.g. ACCESSLOGS=off)

  An way to turn on web access  messages in the web server.  The more appropriate way is the DEBUG entry in coffeemud.ini. Values here include ON, OFF, FILE, or BOTH.

• THROTTLEOUTPUT*=xx
  This is where you specify how many bytes, per second, are allowed to be sent to the specified host.  Specify THROTTLEOUTPUT followed by a forward slash character / and the optional host name and optional port and the context (or just /), and then set that equal to the number of bytes per second to allow in or out.  Specify as many entries as you like.  The throttle treats the number of bytes that applies as a cap to ALL requests, in or out, that apply to a specified host mask.  It will attempt to be fair about distributing load across numerous requests for a given host, and will treat each host mask as a separate pool from other hosts. Remember to escape your colons and backslashes (if you use them)!! Some examples:
  THROTTLEOUTPUT/mydomain.net\:80/contextname=1024
  THROTTLEOUTPUT/localhost\:8080/zimmers=10000000
  
• DUPPOLICY=xx
  How to deal with url parameters or multi-part fields that have the same names.  For example: http://localhost?MYFIELD=bob&MYFIELD=joe&MYFIELD=tom
  Set DUPPOLICY to OVERWRITE to end up only one field where the last value wins.
  Set DUPPOLICY to ENUMERATE to append a number; e.g. MYFIELD=bob MYFIELD1=joe MYFIELD2=tom
  
• CHUNKSIZE=xx
  CHUNKALLOW*=yy
  How to encourage or specify chunked encoding output from the server to clients.  Will only provide chunked output according to the CHUNKHOST entries below. Set CHUNKSIZE to the default chunk size to use when allowed. A value of  0 completely disables chunked responses under all circumstances.  To allow chunked responses at particular domains or urls, enter "CHUNKALLOW" followed by  a forward slash character / and the optional host name and optional port and the  context (or just /), and then set that equal to either an asterisk * or a comma delimited list of mime types to apply chunking to, followed by a colon, followed by the minimum size of a file, in bytes, that may be chunk encoded.  Specify as many entries as you like.  Here are some examples:
  CHUNKALLOW/*\:*/=*:1                  <-- this will chunk everything, basically
  CHUNKALLOW/mydomain.net\:80/contextname=*:1048576
  CHUNKALLOW/texas.localhost\:*/=application/octet-stream,h323,doc:9999999
  
• SERVLET*=javaclass
  For you Java programmers, there is an interface available at com.planet_ink.coffee_web.interfaces.SimpleServlet for creating simple servlet classes.  There is also a SimpleServletRequest and SimpleServletResponse interface for doing your input and output.  When you create such a servlet, you can map it to a top-level url context by using the word "SERVLET" followed by a slash, followed by the root url context, and then setting that equal to the java class name where your SimpleServlet can be found.  Have as many as you like!
  # Check out the example servlets in com/planet_ink/coffee_web/servlets/*.java
  
• DISABLE=true/false
  For developers and those who just don't like functional web servers, this is a comma-delimited list of integrated features you would like to have disabled.  Available features to disable are:  RANGED : the web server will ignore ranged headers and return 200/full document
  
  

Virtual Directories

To permit web access to the files in particular CoffeeMud directories, you can specify MOUNT/virtualdir=physicaldir in the pub.ini or admin.ini files; for example, MOUNT/guides=guides creates a virtual directory with access to the player guides.  If you want, you can also tie particular web hostnames and ports to particular directories.  For example MOUNT/mydomain.com:8080/files=/web/pub would allow browser urls such as http://www.mydomain.com:8080/files to access the /web/pub folder.

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.

Customizing the error page

Simply create a file errorpage.mwhtml 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/WebMacros 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.WebMacros package.

The package of the new class should implement the interface com.planet_ink.coffee_mud.WebMacros.interfaces.WebMacro.

The name() member should return the name of your new macro (it will be capitalized 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 as parameters a reference to the HTPRequest that is calling the macro, and a String representing the data after the first question mark? in the macro reference.

If runMacro() returns null, the string [Error] is used to replace the macro.  If runMacro() returns @break@, this will cause a @loop@-@back@ segment to terminate.

Example: this is the complete code for the @HTTPCLIENTIP@ macro (HTTPclientIP.java):

package com.planet_ink.coffee_mud.WebMacros;

import com.planet_ink.coffee_web.interfaces.*;
import com.planet_ink.coffee_mud.core.interfaces.*;
import com.planet_ink.coffee_mud.core.*;
import com.planet_ink.coffee_mud.core.collections.*;
import com.planet_ink.coffee_mud.Abilities.interfaces.*;
import com.planet_ink.coffee_mud.Areas.interfaces.*;
import com.planet_ink.coffee_mud.Behaviors.interfaces.*;
import com.planet_ink.coffee_mud.CharClasses.interfaces.*;
import com.planet_ink.coffee_mud.Libraries.interfaces.*;
import com.planet_ink.coffee_mud.Common.interfaces.*;
import com.planet_ink.coffee_mud.Exits.interfaces.*;
import com.planet_ink.coffee_mud.Items.interfaces.*;
import com.planet_ink.coffee_mud.Locales.interfaces.*;
import com.planet_ink.coffee_mud.MOBS.interfaces.*;
import com.planet_ink.coffee_mud.Races.interfaces.*;
import java.util.*;

/* 
 Copyright 2000-2026 Bo Zimmerman

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
*/
public class HTTPclientIP extends StdWebMacro
{
	public String name() {return "HTTPclientIP";}

	public String runMacro(HTTPRequest httpReq, String parm)
	{
	if(httpReq.getClientAddress()!=null)
	return httpReq.getClientAddress().getHostAddress();
	return "Unknown";
	}
}

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

Using Javascript in your pages

The CoffeeMud web server allows you to use the Javascript language to generate the tags and data which make up your cmvp web pages. The Javascript to do this is inserted directly into your web page at the point where you want the script-generated content to appear using the embedded macros@jscript@ and @/jscript@. The script included between those two tags will follow the rules for JavaScripting found in the Programmers Guide. The web server makes the HTTPRequest request() object available to the script, as well as the method void write(String s) for writing text into the page.

Here is our first example:

<HTML>
<BODY>
@jscript@
var x=request().getClientAddress().getHostAddress();
write('<P>Your IP Address is <B>'+x+'</B>.</P>');
@/jscript@
</BODY>
</HTML>

Notice how we used the write() method to insert our HTML into the page. We also used the request() object to fetch the client ip address. Now here is a more involved example:

<HTML>
<HEAD>
<TITLE>My JavaScript Enabled Web Page</TITLE>
</HEAD>
<BODY>
<H1>An Example of using JavaScript in a CMVP Web Page to fetch MUD Server data.</H1>

@jscript@
var lib=Packages.com.planet_ink.coffee_mud.core.CMLib;
// define a shortcut to the CoffeeMud libraries.

var randomRoom=lib.map().getRandomRoom();
var randomArea=lib.map().getRandomArea();
// finding random rooms and areas is easy

var randomMob=null;
var randomItem=null;
// assign our random mobs and items to null until they are found

var attempts=1000;
// finding random items and mobs is more difficult. We will
// select a random room, and attempt to pick out a random mob
// and/or item from the room. We will do this a maximum of 1000
// times before giving up, until we find one of each.
while(((--attempts)>0)&&((randomMob==null)||(randomItem==null)))
{
 var room=lib.map().getRandomRoom();
 if((randomMob==null)&&(room.numInhabitants()>0))
 {
 randomMob=room.fetchRandomInhabitant();
 }
 if((randomItem==null)&&(room.numItems()>0))
 {
 randomItem = room.getRandomItem();
 }
} //now we have all our random things. We could easily insert our HTML using
 // the write() method as we did in example 1. To be fancy, however, we'll use the
 // the request() object to assign the names of our selections to HTTP Request
 // strings.

request().addFakeUrlParameter("RANDOMROOM",randomRoom.displayText());
request().addFakeUrlParameter("RANDOMAREA",randomArea.name());
if(randomMob!=null)
 request().addFakeUrlParameter("RANDOMMOB",randomMob.name());
if(randomItem!=null)
 request().addFakeUrlParameter("RANDOMITEM",randomItem.name());
// now we exit back and continue with our HTML, using standard CMVP web macros
// to fetch the random names we saved.
@/jscript@

<FONT FACE="Courier New">
<B>A random area: <B>@RequestParameter?RANDOMAREA@<BR>
<B>A random room: <B>@RequestParameter?RANDOMROOM@<BR>
<B>A random mob : <B>@RequestParameter?RANDOMMOB@<BR>
<B>A random item: <B>@RequestParameter?RANDOMITEM@<BR>

</FONT>
<P>
</BODY>
</HTML>

Servlet interfaces

WebMacroCreamer servlet:

WebSockets in CoffeeMud

• "asciionly" (true/false) to filter out all binary data from "text" packets
• "gmcp" (true/false) to turn GMCP support on or off
• "linefeeds" (true/false) to allow or filter out linefeeds in "text" packets
• "msdp" (true/false) to turn MSDP support on or off
• "msp" (true/false) to turn MSP support on or off
• "mxp" (true/false) to turn MXP support on or off
• "telnet" (true/false) to allow or filter out telnet codes from "text" packets