F140 Documentation

F140 Documentation, v.0.1, Aug. 8, 2010

Author: Chuck Shotton

Please send all comments on this document to my shotton.com address, "chuck@..."

Introduction

This is a strawman document describing a tin can-and-string, federated, 140 character message-passing solution called "F140". This document describes the REST API services for pushing messages and status information between F140 servers. The intent is to keep the number of commands as small as possible, and the payloads as transport-independent as possible.

For all calls documented here, method names and arguments are considered to be case insensitive. Calls are made via HTTP POST or HTTP GET, with the command and arguments sent as URL-encoded form arguments. For example:

http://www.concluent.com:1963/apps/F140/F140Service.html?command=SOMECOMMAND&somearg=cshotton&anotherarg=dingdong

Results are returned in the body of the HTTP response and consist of URL-encoded form arguments. For example:

response=MatchingResponseString

Additional Concepts and Assumptions

The model that F140 is based on relies on peer applications exchanging messages as both clients and servers. The assumption is that each user participating in our can-and-string network has the ability to both send and receive REST service requests. A given F140 node supports at least one user. It may support more than one user locally, but that is an implementation detail.

Each user has a unique username (most likely an email address) that is globally unique across all F140 nodes. For two users to be "friends", each has to know the proper "handshake" to exchange with the other node. F140 relies on a challenge/response system that is negotiated out of band from message traffic. Matching challenge/response pairs may be exchanged and entered manually by two users, or by a more elaborate authentication mechanism implemented in parallel to the PING/MSG methods described here.

A typical implementation is a small HTTP server operating on top of a persistent data store to hold user information, challenge/response pairs, and individual messages. F140 accommodates the concept of "groups", allowing users to collect friends into related groupings that can be targetted by a single message. This allows un-Twitter-like behavior where you can broadcast to only a selected portion of your followers, based on interest, privacy considerations, or any other criteria.

A user will launch a F140 node, which will proceed to contact other nodes it knows about or discovers (discovery process is TBD). When contacting another node via a PING message, the user's node is essentially notifying the remote node of its current address and is requesting that any queued messages for the user be sent in return. If the user creates a message destined for one or more remote nodes, the local F140 node creates a MSG service call and delivers the payload to the appropriate remote node(s). Messages should be queued for offline or unreachable nodes.

In short, the basic implementation behaves very much like SMTP or NNTP where messages are queued for delivery and are transferred from a queue, pushed to the recipient in response to a PING request or by the server according to its internal rules (timers, etc.)

Message Services

These services are related to notifying F140 nodes of presence on the net and for pushing messages from one node to another. The normal sequence of events is for a node to send a PING message to the remote node, indicating a node is now active on the net at a specific service address. The remote node is now free to respond to the sender with one or more MSG commands, transferring any queued messages to the original sender.

As a matter of practice, PING may also be used to "preflight" a subsequent series of MSG calls if the sender wants to confirm that the recipient is still online and active at its last known address.

PING

Inform a remote F140 node that you are present on the network and ready and able to receive any queued messages that might be for you.

Arguments:

username - F140 username the pinging server belongs to (must be globally unique across all F140 servers. email address recommended)
challenge - the challenge string previously agreed upon by both servers through a "friending" process
service_url - the full URL of the REST service where the F140 server hosting "username" can be reached

returns:

response - the matching response to the challenge string

If the response matches the expected response, then the PING message was accepted. Any other non-matching response indicates that the recipient has refused the PING message or the username is not known by or friended with the server being pinged.

MSG

Push a message for a specific user or group to a F140 server. Note that from_user and challenge are used to approve receipt of a message. They may differ from values contained in the message itself. to_user is provided to help a server that may support multiple users route the message traffic appropriately. The triple of from_user:challenge:to_user should be validated to ensure that the sender is a friend of the receiver.

Arguments:

from_user - F140 username of the sender the message is from
challenge - the challenge string previously agreed upon by both servers through a "friending" process
to_user - F140 username the message is to be delivered to (implementations may allow this to be a name of a group of users, allowing further rebroadcast of the message)
mime_type - the MIME type of the payload contained in the message parameter (usually text/plain or text/xml)
message - the message payload, application specific -- likely an XML construct with (possibly multiple) message ID, message data, etc. See Message Types below.

returns:

response - the matching response to the challenge string

If the response matches the expected response, then the MSG was accepted. Any other non-matching response indicates that the recipient has refused the MSG or the username is not known by or friended with the server and user being contacted.

Message Types

Any message format that can be properly encoded and delivered as the body of a HTTP request is acceptable as a "message" argument to a MSG service call. It's really up to the applications on either end of the F140 pipe to manage. For the purposes of experimentation and development, the following message of MIME type 'text/xml' is understood by the F140 server implemented using CORE and should be assumed to be the most basic form supported by all F140 servers:

	<xml>
		<msg kind="basic">
			<id>12345</id>
			<from>cshotton@gmail.com</from>
			<text>This is a 140 character message, more or less.</text>
		</msg>
	</xml>