From: Mark Wooding Date: Mon, 1 Jan 2007 12:52:33 +0000 (+0000) Subject: doc: Document the services messages. X-Git-Tag: 1.0.0pre8~94^3 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/tripe/commitdiff_plain/bdc44f5b72f94c67274ffe8f68d28053d2de2874 doc: Document the services messages. --- diff --git a/doc/tripe-admin.5.in b/doc/tripe-admin.5.in index 6f2ae778..17c83597 100644 --- a/doc/tripe-admin.5.in +++ b/doc/tripe-admin.5.in @@ -65,10 +65,15 @@ All commands can be run as simple commands. Long-running commands and .BR PING ) block the client until they finish, but the rest of the server continues -running. -.SS "Asynchronous messages" -There are three types of asynchronous messages which -aren't associated with any particular command. +running. See +.B "Background commands" +to find out how to issue long-running commands without blocking. +.SS "Asynchronous broadcasts" +There are three types of asynchronous broadcast messages which aren't +associated with any particular command. Clients can select which +broadcast messages they're interested in using the +.B WATCH +command. .PP The .B WARN @@ -92,10 +97,6 @@ Finally, the .B NOTE message is a machine-readable notification about some routine but interesting event such as creation or destruction of peers. -.PP -The presence of asynchronous messages can be controlled using the -.B WATCH -command. .SS "Background commands" Some commands (e.g., .B ADD @@ -150,6 +151,64 @@ response: it will always detach and then issue any lines followed by .B BGOK response. +.SS "Client-provided services" +.\"* 25 Service-related messages +An administration client can provide services to other clients. +Services are given names and versions. A client can attempt to +.I claim +a particular service by issuing the +.B SVCCLAIM +command. This may fail, for example, if some other client already +provides the same or later version of the service. +.PP +Other clients can issue +.I "service commands" +using the +.B "SVCSUBMIT" +command; the service provider is expected to handle these commands and +reply to them. +.PP +There are three important asynchronous messages which will be sent to +service providers. +.SP +.BI "SVCCANCEL " jobid +The named job has been cancelled, either because the issuing client has +disconnected or explicitly cancelled the job using the +.B BGCANCEL +command. +.SP +.BI "SVCCLAIM " service " " version +Another client has claimed a later version of the named +.I service. The recipient is no longer the provider of this service. +.SP +.BI "SVCJOB " jobid " " service " " command " " args \fR... +Announces the arrival of a new job. The +.I jobid +is a simple token consisting of alphanumeric characters which +.B tripe +uses to identify this job. +.PP +The service provider can reply to the job using the commands +.BR SVCINFO , +.B SVCOK +and +.BR SVCFAIL . +The first of these sends an +.B INFO +response and leaves the job active; the other two send an +.B OK +or +.B FAIL +response respectively, and mark the job as being complete. +.PP +(Since +.B SVCSUBMIT +is a potentially long-running command, it can be run in the background. +This detail is hidden from service providers: +.B tripe +will issue the corresponding +.BR BG ... +responses when appropriate.) .SS "Network addresses" A network address is a sequence of words. The first is a token identifying the network address family. The length of an address and @@ -443,6 +502,108 @@ This is useful if firewalling decisions are made based on interface names: a setup script for a particular peer can change the name, and then update the server's records so that they're accurate. .SP +.BI "SVCCLAIM " service " " version +Attempts to claim the named +.IR service , +offering the given +.IR version . +The claim is successful if the service is currently unclaimed, or if +a version earlier than +.I version +is provided; otherwise the command fails with the error +.BR "service-exists" . +.SP +.BI "SVCENSURE " service " \fR[" version \fR] +Ensure that +.I service +is provided, and (if specified) to at least the given +.IR version . +An error is reported if these conditions are not met; otherwise the +command succeeds silently. +.SP +.BI "SVCFAIL " jobid " " tokens \fR... +Send a +.B FAIL +(or +.BR BGFAIL ) +response to the service job with the given +.IR jobid , +passing the +.I tokens +as the reason for failure. The job is closed. +.SP +.BI "SVCINFO " jobid " " tokens \fR... +Send an +.B INFO +(or +.BR BGINFO ) +response to the service job with the given +.IR jobid , +passing the +.I tokens +as the info message. The job remains open. +.SP +.B "SVCLIST" +Output a line of the form +.RS +.IP +.B INFO +.I service +.I version +.PP +for each service currently provided. +.RE +.SP +.BI "SVCOK " jobid +Send an +.B OK +(or +.BR BGINFO ) +response to the service job with the given +.IR jobid . +The job is closed. +.SP +.BI "SVCQUERY " service +Emits a number of +.B info +lines in key-value format, describing the named +.IR service. +The following keys are used. +.RS +.TP +.B name +The service's name. +.TP +.B version +The service's version string. +.RE +.SP +.BI "SVCRELEASE " service +Announce that the client no longer wishes to provide the named +.IR service . +.SP +.BI "SVCSUBMIT \fR[" options "\fR] " service " " command " " arguments \fR... +Submit a job to the provider of the given +.IR service , +passing it the named +.I command +and the given +.IR arguments . +The following options are accepted. +.RS +.\"+opts +.TP +.BI "\-background " tag +Run the command in the background, using the given +.IR tag . +.TP +.BI "\-version " version +Ensure that at least the given +.I version +of the service is available before submitting the job. +.RE +.\"-opts +.SP .BI "STATS " peer Emits a number of .B INFO @@ -533,15 +694,15 @@ its version string. The server name is reserved to the Straylight/Edgeware implementation. .SP .BR "WATCH " [\fIoptions\fP] -Enables or disables asynchronous messages +Enables or disables asynchronous broadcasts .IR "for the current connection only" . See .B "Trace lists" above. The default watch state for the connection the server opens automatically on stdin/stdout is to show warnings and trace messages; -other connections show no asynchronous messages. (This is done in order -to guarantee that a program reading the server's stdout does not miss -any warnings.) +other connections show no asynchronous broadcast messages. (This is +done in order to guarantee that a program reading the server's stdout +does not miss any warnings.) .RS .PP Message types provided are: @@ -623,6 +784,13 @@ An error occurred during the attempt to become a daemon, as reported by .BR ADD .) The given port number is out of range. .SP +.BI "not-service-provider " service +(For +.BR SVCRELEASE .) +The invoking client is not the current provider of the named +.IR service , +and is therefore not allowed to release it. +.SP .BI "peer-create-fail " peer (For .BR ADD .) @@ -655,6 +823,25 @@ The DNS name .I hostname took too long to resolve. .SP +.BI "service-exists " service " " version +(For +.BR SVCCLAIM .) +Another client is already providing the stated +.I version +of the +.IR service . +.SP +.BI "service-too-old " service " " version +(For +.B SVCENSURE +and +.BR SVCSUBMIT .) +Only the given +.I version +of the requested +.I service +is available, which does not meet the stated requirements. +.SP .BI "tag-exists " tag (For long-running commands.) The named .I tag @@ -684,6 +871,17 @@ The port name couldn't be found in .BR /etc/services . .TP +.BI "unknown-service " service +(For +.BR SVCENSURE , +.BR SVCQUERY , +.BR SVCRELEASE , +and +.BR SVCSUBMIT .) +The token +.I service +is not recognized as the name of a client-provided service. +.TP .BI "unknown-tag " tag (For .BR BGCANCEL .) @@ -739,6 +937,17 @@ as a result of a .B SETIFNAME command. .SP +.BI "SVCCLAIM " service " " version +The named +.I service +is now available, at the stated +.IR version . +.SP +.BI "SVCRELEASE " service +The named +.I service +is no longer available. +.SP .BI "USER " tokens\fR... An administration client issued a notification using the .B NOTIFY