Transient Service Registration Protocol - Reggie Copyright (c) Matt Slot, 3/27/97, Status ------ This document describes a proposed solution to the needs of those who provide client-server services across the Internet. The protocol and a sample implementation are in progress, so please send comments as soon as possible. The resulting protocol and implementation will be placed into the public domain to encourage adoption. Overview -------- The Transient Service Registration Protocol, also called TSRP or Reggie, is designed to mediate client-server connections in a wide area network. It specifically addresses the following needs: * Provide simple but extensible service advertising, with control over scope. * Provide simple but extensible service location, including wildcard searches and segmented retrieval of results. * Provide simple but extensible service notification in a timely fashion, without active polling. * Provide datagram and stream based access, with transaction controls. * Eliminate broadcast or multicast service location by clients. * Allow for scalable backbone of service locators. * Allow transparent connection using DNS extensions. * Suitable for short- and medium-lived services. This implementation is superior to other similar services, such as NBP and SrvLoc, which often use subnetwork broadcast or reserved multicast addresses. It also surpasses LDAP, which manages directories of long term data. The protocol is designed to allow flexibility when designing the interface at the client side. Possible browsers include scrollable lists or a browser with collapsible headings (such as domains). Requests can be made in small segments to facilitate paging through large amounts of data, and wildcard queries are suitable for power users. Terminology ----------- Service Provider: A software process that provides interprocess, serial, or network access to its services. Also called the "server" or "provider". Service Client: A software process that desires a listing of or access to the services of a Service Provider. Also called the "client". Service Broker: A software process that acts a repository for data regarding one or more Service Providers, which then disseminates that information to Service Clients who request it. Also called the "broker" Service Gateway: A software process that acts as a medium between a Service Broker and 3rd party services that provide similar functionality (ala, NBP, Internet Trackers). Messages: --------- Register, Unregister, Query, Answer, Acknowledgement Register Service: 0 +---------+---------+---------+---------+ | length | checksum | 4 +---------+---------+---------+---------+ | transaction type | transaction flags | 8 +---------+---------+---------+---------+ | transaction id | C + + + + + | | 10 +---------+---------+---------+---------+ | time to live | 14 +---------+---------+---------+---------+ | reserved | 18 +---------+---------+---------+---------+ | | 1C + + + + + | host address | 20 + + + + + | | 24 + + + + + | | 28 +---------+---------+---------+---------+ | | / tuple list / | | n +---------+---------+---------+---------+ Unregister Service: 0 +---------+---------+---------+---------+ | length | checksum | 4 +---------+---------+---------+---------+ | transaction type | transaction flags | 8 +---------+---------+---------+---------+ | transaction id | C + + + + + | | 10 +---------+---------+---------+---------+ | | 14 + + + + + | host address | 18 + + + + + | | 1C + + + + + | | 20 +---------+---------+---------+---------+ Query: 0 +---------+---------+---------+---------+ | length | checksum | 4 +---------+---------+---------+---------+ | transaction type | transaction flags | 8 +---------+---------+---------+---------+ | transaction id | C + + + + + | | 10 +---------+---------+---------+---------+ | answer range | 14 + + + + + | | 18 +---------+---------+---------+---------+ | time to live | 1C +---------+---------+---------+---------+ | | / tuple list / | | n +---------+---------+---------+---------+ Answer: 0 +---------+---------+---------+---------+ | length | checksum | 4 +---------+---------+---------+---------+ | transaction type | transaction flags | 8 +---------+---------+---------+---------+ | transaction id | C + + + + + | | 10 +---------+---------+---------+---------+ | answer count | 14 +---------+---------+---------+---------+ | answer index | 18 +---------+---------+---------+---------+ | | 1C + + + + + | host address | 20 + + + + + | | 24 + + + + + | | 28 +---------+---------+---------+---------+ | | / tuple list / | | n +---------+---------+---------+---------+ Acknowledgement: 0 +---------+---------+---------+---------+ | length | checksum | 4 +---------+---------+---------+---------+ | transaction type | transaction flags | 8 +---------+---------+---------+---------+ | transaction id | C + + + + + | | 10 +---------+---------+---------+---------+ Data Types: Length: Number of bytes in packet, including length Checksum: Standard packet CRC checksum (0 if unused) Transaction Type: Enumerated packet types Transaction Flags: Enumerated packet flags -- 0x0001 = require ACK Transaction ID: Unique ID for this transaction (0 if unused) Time To Live: Number of seconds from receipt before expiration Host Address: BSD socket address (eg, AF_INET, Port, Host, 8 bytes filler) Tuple List: List of an arbitrary number of data tuples (may be empty) Answer Range: Index of first and last entry requested (0 to return count) Answer Count: Number of matches to client request Answer Index: Index of matching entry returned (one-based index) Tuple List: . . . Key: String of a-z, A-Z, 0-9, '-', and '_' (case sensitive) Data: String of ASCII from 0x20 (' ') to 0x7E ('~') Duplicate keys are allowed, and are treated as setwise-OR. Expected data strings include: value: Signed 32-bit value as string (include leading '+' or '-') string: Simple non-control ASCII character string address: Protocol-dependent network address rich: Base64 encoding data (text, binary) list: Tab-separated data, value-list, string-list Well-Defined Tuples: ------------------- Uppercase keys are reserved. Mixed and Lowercase keys are free for application definition. The following are "well-defined" keys/data tuples: SCOPE: Global service scope: 0=Local, 1=Global, 2=Americas, 3=Europe/Africa, 4=Asia/Australia. (default=0) DOMAIN: Local network name, eg "netscape.com", "engin.umich.edu" CONTACT: Adminstrative or technical contact, eg "Bob Smith, webmaster@here.com" SERVICE: Unique type of network service, eg "ftp", "http", "tsrp" URL: Standard URL descriptor, eg "telnet://cool.mud.org:50000/" ICON: Encoded 32x32 GIF or JPEG icon NAME: Name of network service, eg "Info-Mac Archives", "Netscape Webserver" MESSAGE: Name of network service, eg "Current load is 5 users, come on in!" AUTHENTICATION: Type of authentication: "None", "Guest", "Text", "Kerberos" (default="None") Sample Tuple List: SCOPE:0 DOMAIN:ambrosiasw.com CONTACT:Cajun, help@ambrosiasw.com SERVICE:http URL:http://www.ambrosiasw.com/ NAME:Ambrosia Software Homepage webserver:Netscape Secure Server x-current-load:5 Transactions: ------------- 1a) PROVIDER, GATEWAY BROKER -- REGISTER --> <---- ACK ----- 1b) PROVIDER, GATEWAY BROKER - UNREGISTER -> <---- ACK ----- To register a service, a Service Provider or its proxy sends a register packet with the appropriate host entry and information tuple-list. If the ack-flag is set, the broker will acknowledge the transaction using the same transaction ID. To unregister a service, the Service Provider or its proxy sends an unregister packet with the appropriate host entry for the service to remove. The implementation may decide whether only the process that registered the service is allowed to unregister a service, or whether anyone one can. If the ack-flag is set, the broker will acknowledge the transaction using the same transaction ID. ----- 2a) CLIENT BROKER --- QUERY ----> <--- ANSWER --- 2b) CLIENT BROKER --- QUERY ----> <--- ANSWER --- <--- ANSWER --- <--- ANSWER --- 2c) CLIENT BROKER --- QUERY ----> <--- ANSWER --- ... time ... <--- ANSWER --- ---- ACK -----> There are several ways to query and retrieve entries from the Broker. To initiate a transaction, a Client sends a query packet with a unique transaction ID and the desired "answer range". The Broker upon receipt of a "query transaction", stores the full results in temporary memory, and begins responding to the client requests. To retrieve results of the previous query, the client uses the same transaction ID; to make a new query (and invalidate the last one), the client generates a unique transaction ID. The transaction ID and results remain valid until another query packet is received from the same client or after a sufficient timeout (eg, 1 hour). To retrieve the number of results without retrieving an entry, request entry number zero. To retrieve a specific range of results, send a query with the desired range indices. To request passive notification as new services come online, change, or shut down, passes the index -1. To cancel a passive notification, make another query with a unique transaction ID. Answers to queries include the total number of results and the index of the result. Passive notifications include a valid index number, so that you can identify new, changed, or removed services. A new service lists a new index and a full tuple-list. A changed service lists the original index and a new tuple-list. A removed service lists the original index and an empty tuple-list.