Pathfinder (pathfinder)
Pathfinder is an HTTP server that allows users to access MASH tools via the Web. The server currently supports the following tools:
- SDR - session announcement agent
- ARIES - recording agent
- MARS - archive playback tool
With these tools, a user is able to use the web browser to select from a list of sdr session announcements, view and/or record a session, and request play of archived sessions. Since the server is a Web-based tool, user operation is relatively self-explanatory. Therefore, this document provides information required for running the server and augmenting its functionality.
1. Running the Server
The following section provides step-by-step instructions on how to run the Pathfinder Server (pathfinder) and the supporting status checker which periodically polls the server for its status and restarts the server when it goes down. If you are building from source, see the instructions on how to make mash and the pathfinder script.
- Copy the sample prefs file to the ~/.mash/ directory and change it's name to prefs-pathfinder; this file is located in the following directory: mash-1/tcl/applications/pathfinder/.
- Make appropriate changes to the prefs file; the various fields of the prefs file are described in Appendix A.
- Run the server by typing "pathfinder >& [output dir]/output.txt &." The server currently defaults to port 4444. Note that the output dir is that wihch is specified in the prefs file.
- From the mash-1 directory. run the status checker by typing "bin/smash tcl/applications/pathfinder/status_checker.tcl >& [output dir]/status_output.txt &"
You may have to wait a short time before SDR sessions appear. To see the latest announcements you must reload the "Live Session Announcements" page, new entries will not be pushed to your browser.
2. Augmenting the Server's Functionality
This section covers the steps required to add a new Agent to the Pathfinder Server. This begins with a description of the overall structure of the server, followed by information useful in writing a MASH HTTP_Agent, and finally instructions for adding the new Agent to the server.
2.1. The Overall Structure
The pathfinder server basically acts as a frontend to the Web which MASH HTTP_Agents are able to plug into. When the it receives a HTTP request, the server simply passes relevant information extracted from the URL to each of the Agents. The URL and associated information are then examined by each Agent to determine whether the request is relevant to that Agent's funcationlity. This is done through a mechanism of "magic URLs." A typical magic URL takes the following forms:
http://spade:4444/[dynamic or non-dynamic html page]
http://spade:4444/[function]^[SDP Message unique key]
2.2. Writing an HTTP_Agent
The only requirement of an HTTP Agent that plugs into the MASH Server is that it has a handle_request method. This method takes as arguemnts a url, key, and source and returns a list containg the page, status, and type. These arguemtsn and return values are described in more detail below:
- url: this is either an html page or the function name portion of the request (i.e. that which comes before the ^)
- key: this is the argument that follows the ^; typically this is some unique key which identifies the object on which some action will be performed.
- source: the machine name of the requestor's source
- page: the HTML page or data that is to be returned
- status: the numerical HTTP return code (e.g. 200 = OK)
- type: the mimetype of the page or data being returned (e.g. text/html)
Although, the handle_request method is the only requirement for HTTP Agents, one may find it useful to derive the new Agent from the HTTP_Agent class. This class contains some helper functionsn that the writer of the new Agent may find helpful. Please refer to http_agent.tcl for more information on these functions and their usage.
2.3. Adding an Agent to the Server
In main.tcl of the pathfinder directory, do the following:
- Create an instance of the new Agent.
- Add the agent with the command "$server add_agent [your agent]."
Appendix A: Prefs Fields
- html_dir: the directory in which the dynamic and non-dynamic HTML files are stored
- archive_root: the main archive directory
- archive_dir: the subdirectory within the main archive directory where recording agent stores recorded sessions
- sdp_sessions_dir: the sdr agent's cache
- rec_schedule_dir: the directory that the recording agent uses to store a schedule of current and future recordings
- play_server_addr: the multicast address used by MARS
- max_duration: the maximum duration for recordings in minutes
- email_addr: the email address to which status notifications are sent
- output_dir: the directory in which status_checker and pathfinder is redirected
- server_addr: the MASH Server's address
- server_port: the MASH Server's port
- mashlet_dir: the URL that will be used as the TCLCL_IMPORT_DIRS environment variable in dynamically generated mashlets
- ping_freq: the frequency (in seconds) at which the status_checker polls the server
- valid_clients: a regular expression describing from which machines recording is allowed