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
.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
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
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
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:
.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 .)
.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
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 .)
.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
~mdw / tripe / blobdiff