chiark / gitweb /
doc: Document the services messages.
authorMark Wooding <mdw@distorted.org.uk>
Mon, 1 Jan 2007 12:52:33 +0000 (12:52 +0000)
committerMark Wooding <mdw@distorted.org.uk>
Mon, 1 Jan 2007 12:52:33 +0000 (12:52 +0000)
doc/tripe-admin.5.in

index 6f2ae77..17c8359 100644 (file)
@@ -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