Every Gale message has a set of "categories" which determine where it gets sent and who it gets delivered to. Every Gale subscriber has a set of "subscriptions" which determine what messages they receive. At its heart, Gale is a big distributed system for matching categories against subscriptions and delivering messages appropriately. This document explains the specific details of how categories and subscriptions are constructed.
Categories may contain two parts, a "domain" and a "subcategory":
@ | Domain example.com | / | Subcategory sports.baseball.mets |
The domain is optional; if it is not present, neither are the '@' and '/' delimiters. If present, the domain must be a valid "gale domain". Gale domains are usually the same as the Internet domain name of a system running a Gale server. Examples of valid domains are "ofb.net", "ugcs.caltech.edu", and "example.gale.org". The subcategory may be any string that does not contain a colon (":").
All messages have one or more categories; multiple categories are combined with colons, e.g. "@ugcs.caltech.edu/user/egnor/:@ofb.net/group". The message is considered to have all the listed categories; order doesn't matter.
A minus ("-") as the first character of a category has the special meaning of "negating" the category; see the section on subscription matching below. (Negative categories are rarely used.)
A subscription has the same form as a category. It is said to "match" any category which has the same domain and whose subcategory starts with the subscription's subcategory. For example, consider the subscription "@example.com/sports.baseball":
| Matches | Does not match | ||
|---|---|---|---|
|
@example.com/sports.baseball @example.com/sports.baseball/ @example.com/sports.baseball.mets @example.com/sports.baseballers @example.com/sports.baseball-sucks @example.com/sports.baseball/pool |
@example.com/sports @example.com/sports.football @example.com/sports/baseball @other.com/sports.baseball |
Note that delimiters used within subcategories (such as "." and "/") are simply a matter of convention; subcategory matching is done on a character-by-character basis without regard to punctuation.
Users specify a "subscription list" which consists of one or more subscriptions, combined with colons. Like categories, subscriptions may begin with a minus. Such a "negative subscriptions" matches the same categories it would without the minus, but has the opposite effect when matching (see below).
Generally speaking, if one of a user's subscriptions matches one of a message's categories, then the user receives the message. Negative subscriptions cause the user not to receive the message; in the presence of a conflict, the last matching subscription takes precedence.
More precisely, for each message, the matching process iterates through the user's subscriptions, from first to last. Initially, the message is considered "unselected", i.e. the user will not receive the message. Whenever a subscription matches any of the message's categories, the message is set to "selected" for that user if the subscription is positive (normal) or unselected if the subscription is negative. After the last of the user's subscriptions is processed, if the message is selected, it will be sent to the user, otherwise it will not. (This process executes independently for all users, and of course the actual implementation is more efficient, though it has the same outcome.)
Categories themselves may also be negated with a minus. Whenever a negative category matches a subscription, that subscription is considered to be negative as well (whether or not it was negative to begin with). This isn't very useful, and so negative categories are rarely used, except by the Gale internals.
For example, consider the subscription list "@example.com/sports:-@example.com/sports.football:@somewhere.com/user/me:-flame":
| Messages received: | Not received: | ||
|---|---|---|---|
|
@example.com/sports.baseball.mets @somewhere.com/user/me @example.com/sports.football.giants:@somewhere.com/user/me/hello @elsewhere.com/stuff:@example.com/sports/soccer -@example.com/sports.baseball:@somewhere.com/user/metoo |
@example.com/sports.football @example.com/sports.soccer:@example.com/sports.football @example.com/sports.soccer:flame @example.com/sports.soccer:@somewhere.com/user/me:flame @example.com/sports.soccer:@somewhere.com/user/me:-flame @elsewhere.com/something.else -@example.com/sports.baseball:@example.com/sports.soccer |
You can find lists of well-known categories on the Gale home page. You may wish to scan the reference for gsub and gsend for specifics on how to transmit messages and subscribe to categories. The Administrators' Documentation describes (among other things) how to set up new gale domains. Finally, if you want to find out more about the implementation of category matching, see the Architecture Guide.