Mango initially treats all clients as anonymous connections. A limited number of commands, those deemed non-sensitive are available. Most commands, however, require that the server know who the client is. The client therefore has to authenticate itself to the server. This authentication can take the form of a broad trust (the client is a member of a "group", such as a web server or an administrator) or a specific trust (the client is Frank Drakman III). Mango supports the following authentication methods:
For broad trusts, Mango has several different authentication levels. The levels are identified by the key name used during the authentication process.
For specific trusts the client can execute any command on behalf of themselves only. The exceptions to this rule is if the client is an administrator, in which case they can execute any command on behalf of anybody inside their administration realm, or a superuser, in which case they can execute any command (equivalent to the wmango broad trust).
In determining whether a client is permitted to execute a command, Mango goes through the following sequence:
Communication between the client and server can optionally be encrypted for greater security. The client specifies using the API function MGOinitialize() which authentication method is desired, and whether encrypted communications are needed.
The Mango server is a general-purpose transaction server designed for easy extensibility. It consists of a listener and one or more workers. Clients issue commands to the listener, who schedules them to a worker, who performs the action and returns the results back to the listener, who relays the results back to the client.
The listener handles connections and communications between itself and its clients and/or workers. When a client connects to Mango, the listener accepts the new connection and sets up a profile. This profile contains information about the client, such as who it is and where it's coming from. Initially, a client is considered to be anonymous - part of the unwashed masses.
Once connected, clients can begin sending commands to the server. All commands are categorized by an access level (along with possibly other information). Some commands can be executed by any client, while others require the client authenticate itself first in order to obtain the proper credentials to execute the command. Client authentication is performed thru the admit command, which employs one of the methods outlined in the access control section.
When a client issues a command, the listener places the comand on its request queue. The scheduler task takes the command from the request queue and hands it over to a free worker for execution. Commands are executed in the order received, so the client will never receive out-of-order responses.
Responses to commands are prefixed with one of three keywords: ack, meaning the command succeeded, nak, meaning the command failed, or eod, indicating no more data for that command. A command may generate several acks or naks, but only one eod.
Depending on how the server is configured and which client options are specified at connect time, a client can be dropped for one of the following reasons:
Of course, a client can also be dropped for other error conditions which may crop up during the normal course of operations.
The Mango API provides clients a standard way of communicating with the server. There are a number of rules which control authentication and connection to the server, along with a large set of function calls.
Most Mango functions return a value of 0, indicating that it was unsuccessful given the arguments; a positive value, indicating the number of "items" that were affected or returned by the function; or -1, indicating some error. The error code is stored in MGOerrno, which correspond to the MGO_E_xxx error codes listed in mgoapi.h and the error text is in MGOerrmsg, which is suitable for display or diagnostic logging.
Connecting to the server is done via MGOconnect(). A number of rules, established with MGOinitialize(), control how the connection is made. MGOdisconnect() disconnects you from the server. If there are no Mango servers available, an error code of MGO_E_NSV is returned, indicating that the service may be temporarily down and to try again later. If an established connection is dropped for whatever reason, the API functions will automatically try to re-establish the connection. If it cannot be re-established, an appropriate error message will be set and the function will fail accordingly.
All unset variable and struct arguments must be initialized to the Mango-specific "empty" value before passing on to the API functions. For ints this value is EIV; for chars and structs its ESV. These values are not the same as NULL or 0, so don't use bzero() or equivalent. Instead, do:
These are necessary so that the functions can distinguish between a cleared and an unset variable. An unset variable means that you don't want to change its value, whereas a cleared variable means that you do.
This group are the low-level functions, having to do mainly with communicating with the server, manipulating data, etc.
This group are the primitive functions, which perform simple operations. Consider these to be the building blocks for more sophisticated functions.
This group are the advanced functions, which perform complex operations. Use these instead of a primitive function whenever possible.
A simple command, mu, allows you to connect directly to the server and issue commands interactively. It has a number of options, most of which you'll probably never need to specify:
mu [-c config] [-f keyfile] [-h host] [-i command] [-k key] [-m method] [-o options] [-p port] [-q] [-s server] [-u usecc] [-w pwdsalt] [-z]