API

Overview

Coma is built on top of a series of base classes (objects) that store all the runtime variables. The API defines these objects and how they are used. Each object must have the following characteristics:

• Must be thread safe
• Must be simple enough to be mapped to a Javascript counterpart
• Must incorporate security authorization if object exposes restricted functionality

Thread Safety

Chances are that some of these objects are being referenced by more than a single thread. Because of this, data access must be encompassed by a mutual exclusion mechanism.

Javascript Friendly

Each object must be representable as a Javascript object. Functions should process data types that are compatible with Javascript data types.

Security

Objects that expose potential security issues, such as the file system or networking, must extend a base security class. Objects are scoped to a context: server, site, connection, and request. By default, scopes cascade down security rights.

Any code compiled into the main executable is considered to be trusted and has full access to any object in any scope.

The server must be explicitly told each native C++ modules and Javascript modules to dynamically load and what scope they belong to. Server scoped modules must be explicitly told to allow access from lesser scopes using access control lists.

Scopes

There are 4 scopes:

• Server
• Top level global scope
• Must explicitly be allowed read-only or read/write access to each site
• Stores system info (os, hardware, etc)
• Stores server-wide configuration settings
• Site
• Only accessible to a particular site
• Stores site specific info (name, ip, port, etc)
• Connection
• Stores information about a particular connection (session id, user id, etc)
• Expires after timeout or disconnect
• Request
• Stores information about a request
• Expires after request has ended

Server Process Flow

This describes the process flow of how the server runs.

• create logger
• init stderr
• create server
• init server
• create server js runtime
• create coma global namespace
• create server registry
• init server registry
• system info
• hardware (memory, cpus, storage, network)
• os (version, limits, capabilities)
• configuration defaults
• load environment variables
• load command line arguments
• if invalid, show usage and exit
• load configuration file
• update logger
• enable/disable syslog & file
• clean up log directory?
• load modules
• init sites
• bind to ips/ports
• load native & script modules
• init ssl
• create js runtime
• init thread pool
• create js contexts for each site
• deamonize?
• force single instance?
• create pid file defined in config
• drop root privileges
• permanently?
• switch user/group/dir defined in config
• run server
• connect to peers?
• listen for connections
• on connect, delegate connection to thread
• delete pid file
• exit

Settings

Settings are either defined as environment variables, command line arguments, or in the configuration file.

Environment Variable	Command Line Argument	Config File	type	default	Description
COMA_CONFIG_URL	-configUrl	n/a	string	file:///etc/coma/conf.js	The URL to the configuration. Supported protocols are file and http.
COMA_USE_SYSLOG	-useSyslog	logging.syslog	bool	false	Enables outputting of log messages to syslogd.
COMA_LOG_PATH	-logPath	logging.path	string	/var/logs/coma	The path to write log files.
COMA_PID_FILE	-pidFile	n/a	string	/var/run/comad.pid	The location of the process ID file.

Subscribers

Overview

Coma will support multiple types of subscribers.

• Typical comet subscribers (browsers, Flash, etc)
• Trigger subscribers
• Execute a URL
• Invoke a web service

Target Platforms

Coma is designed to run on the latest 64-bit multi-core processors from Intel, AMD, and Sun Microsystems. The majority of Unix-like operating systems will be supported including:

• Linux
• Solaris
• Mac OS X

FreeBSD may also be targeted. Windows will not.
It is also critical that Coma operate to the best capacity within a virtual machine such as Xen, Parallels, and VMWare.