Understanding the Network Connections in LambdaMOO

Accepting and Initiating Network Connections

When the server first accepts a new, incoming network connection, it is given the low-level network address of computer on the other end. It immediately attempts to convert this address into the human-readable host name that will be entered in the server log and returned by the connection_name() function. This conversion can, for the TCP/IP networking configurations, involve a certain amount of communication with remote name servers, which can take quite a long time and/or fail entirely. While the server is doing this conversion, it is not doing anything else at all; in particular, it it not responding to user commands or executing MOO tasks.

By default, the server will wait no more than 5 seconds for such a name lookup to succeed; after that, it behaves as if the conversion had failed, using instead a printable representation of the low-level address. If the property name_lookup_timeout exists on $server_options and has an integer as its value, that integer is used instead as the timeout interval.

When the open_network_connection() function is used, the server must again do a conversion, this time from the host name given as an argument into the low-level address necessary for actually opening the connection. This conversion is subject to the same timeout as in the in-bound case; if the conversion does not succeed before the timeout expires, the connection attempt is aborted and open_network_connection() raises E_QUOTA.

After a successful conversion, though, the server must still wait for the actual connection to be accepted by the remote computer. As before, this can take a long time during which the server is again doing nothing else. Also as before, the server will by default wait no more than 5 seconds for the connection attempt to succeed; if the timeout expires, open_network_connection() again raises E_QUOTA. This default timeout interval can also be overridden from within the database, by defining the property outbound_connect_timeout on $server_options with an integer as its value.

Associating Network Connections with Players

When a network connection is first made to the MOO, it is identified by a unique, negative object number. Such a connection is said to be un-logged-in and is not yet associated with any MOO player object.

Each line of input on an un-logged-in connection is first parsed into words in the usual way (see the chapter on command parsing for details) and then these words are passed as the arguments in a call to the verb $do_login_command(). For example, the input line

connect Munchkin frebblebit

would result in the following call being made:

$do_login_command("connect", "Munchkin", "frebblebit")

In that call, the variable player will have as its value the negative object number associated with the appropriate network connection. The functions notify() and boot_player() can be used with such object numbers to send output to and disconnect un-logged-in connections. Also, the variable argstr will have as its value the unparsed command line as received on the network connection.

If $do_login_command() returns a valid player object and the connection is still open, then the connection is considered to have logged into that player. The server then makes one of the following verbs calls, depending on the player object that was returned:

$user_created(player)
$user_connected(player)
$user_reconnected(player)

;listeners() 	=> {{#650, 7778, 0}, {#0, 7777, 1}}
			=> #0  (The System Object) => #650  (HTTP Service)
#0:do_login_command   this none this
 1:  "...This code should only be run as a server task...";
 2:  if (callers())
 3:    return E_PERM;
 4:  endif
 5:  if (typeof(h = $network:incoming_connection(player)) == OBJ)
 6:    "connected to an object";
 7:    return h;
 8:  elseif (h)
 9:    return 0;
10:  endif
11:  host = $string_utils:connection_hostname(connection_name(player));
12:  if ($login:redlisted(host))
13:    boot_player(player);
14:    server_log(tostr("REDLISTED: ", player, " from ", host));
15:    return 0;
16:  endif
17:  "...checks to see if the login is spamming the server with too many commands...";
18:  if (!$login:maybe_limit_commands())
19:    args = $login:parse_command(@args);
20:    return $login:(args[1])(@listdelete(args, 1));
21:  endif

#650:do_login_command   this none this
 1:  if (length(args) > 1)
 2:    try
 3:      if (args[1] == "get" || args[2] == "post")
 4:        this:(args[1])(@listdelete(args, 1));
 5:      endif
 6:    except v (ANY)
 7:    endtry
 8:    "A hack to delay for output to reach the client.";
 9:    suspend(2);
10:    boot_player(player);
11:    return -1;
12:  else
13:    return -1;
14:  endif

The first of these is used if the returned object number is greater than the value returned by the max_object() function before $do_login_command() was invoked, that is, it is called if the returned object appears to have been freshly created. If this is not the case, then one of the other two verb calls is used. The $user_connected() call is used if there was no existing active connection for the returned player object. Otherwise, the $user_reconnected() call is used instead.