<commit_before>.\" pump.socket.7
.\"
.\" pump.socket(7) manual page
.\"
.\" Copyright 2018 <NAME> <<EMAIL>>
.\"
.\" Licensed under the Apache License, Version 2.0 (the "License");
.\" you may not use this file except in compliance with the License.
.\" You may obtain a copy of the License at
.\"
.\"     https://www.apache.org/licenses/LICENSE-2.0
.\"
.\" Unless required by applicable law or agreed to in writing, software
.\" distributed under the License is distributed on an "AS IS" BASIS,
.\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.\" See the License for the specific language governing permissions and
.\" limitations under the License.
.Dd June 19, 2018
.Dt PUMP.SOCKET 7
.Os
.Sh NAME
.Nm pump.socket
.Nd protocol for pump.io's control socket
.Sh DESCRIPTION
.Nm
is a Unix domain socket that uses a simple line-based protocol to control a running pump.io daemon.
This protocol can be used to request actions and query information.
.Ss Protocol semantics
Command names are written directly to the socket followed by a newline and will be responded to with either
.Ql ACK
or
.Ql NACK
for success or failure, respectively.
.Ql NACK
responses will always append a space followed by a reason string for the failure; exactly what these reasons can be will depend on the command.
However, any unrecognized command will always return the reason string
.Ql unknown .
Reason strings may contain any character except newline and null, including whitespace, and are terminated by a newline character.
Reason strings may be assumed to be stable across pump.io versions.
.Pp
Certain commands may also return data.
In this case, a space followed by the data is appended to the
.Ql ACK
response.
Like
.Ql NACK
reason strings, the may contain any character except newline and null, and is terminated by a newline.
Commands that don't return data will respond with
.Ql ACK
directly followed by a newline.
.Pp
The client is not required to wait for an
.Ql ACK
or
.Ql NACK
response before sending another command unless it either needs information from the first command before proceeding or wants to be sure that the first command succeeded before sending the second.
Command names are case-insensitive but traditionally written in uppercase.
.Pp
Blank lines are silently ignored.
The client is not required to close the connection in any way besides disconnecting from the socket; it is also not required to wait for
.Ql ACK
or
.Ql NACK
responses from the server.
Any responses that would have been written after the socket is closed will be silently dropped.
.Ss Available commands
.Bl -tag -width Ds
.It Ic CMDS
Returns a space-separated, uppercase list of commands the daemon understands.
Does not return
.Ql NACK .
.It Ic VERSION
Returns the version of the running daemon's master process.
Does not return
.Ql NACK .
.It Ic RESTART
Triggers a zero-downtime restart.
Receipt of an
.Ql ACK
does not indicate that the restart has completed; merely that it has been queued for processing.
.Ql NACK
reason strings may be one of
.Ql no workers
if there aren't enough workers available;
.Ql bad driver
if zero-downtime restarts aren't available on the current Databank driver;
.Ql aborted restart
if a previous restart attempt failed;
.Ql restart in flight
if there's already an ongoing restart attempt; or
.Ql incompatibility
if the new version indicates an incompatibility.
If the reason string is
.Ql aborted restart
, the program should warn the user to restart pump.io as soon as possible.
.Pp
Other reason strings may be added to this command in the future.
.El
.Sh FILES
By default the control socket is created owner read-write at
.Pa /var/run/pump.socket .
The owner will depend on whoever started the daemon.
.Pp
The location can be influenced by the<commit_msg>Fix extra space in pump.socket(7)<commit_after>.\" pump.socket.7
.\"
.\" pump.socket(7) manual page
.\"
.\" Copyright 2018 <NAME> <<EMAIL>>
.\"
.\" Licensed under the Apache License, Version 2.0 (the "License");
.\" you may not use this file except in compliance with the License.
.\" You may obtain a copy of the License at
.\"
.\"     https://www.apache.org/licenses/LICENSE-2.0
.\"
.\" Unless required by applicable law or agreed to in writing, software
.\" distributed under the License is distributed on an "AS IS" BASIS,
.\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.\" See the License for the specific language governing permissions and
.\" limitations under the License.
.Dd June 19, 2018
.Dt PUMP.SOCKET 7
.Os
.Sh NAME
.Nm pump.socket
.Nd protocol for pump.io's control socket
.Sh DESCRIPTION
.Nm
is a Unix domain socket that uses a simple line-based protocol to control a running pump.io daemon.
This protocol can be used to request actions and query information.
.Ss Protocol semantics
Command names are written directly to the socket followed by a newline and will be responded to with either
.Ql ACK
or
.Ql NACK
for success or failure, respectively.
.Ql NACK
responses will always append a space followed by a reason string for the failure; exactly what these reasons can be will depend on the command.
However, any unrecognized command will always return the reason string
.Ql unknown .
Reason strings may contain any character except newline and null, including whitespace, and are terminated by a newline character.
Reason strings may be assumed to be stable across pump.io versions.
.Pp
Certain commands may also return data.
In this case, a space followed by the data is appended to the
.Ql ACK
response.
Like
.Ql NACK
reason strings, the may contain any character except newline and null, and is terminated by a newline.
Commands that don't return data will respond with
.Ql ACK
directly followed by a newline.
.Pp
The client is not required to wait for an
.Ql ACK
or
.Ql NACK
response before sending another command unless it either needs information from the first command before proceeding or wants to be sure that the first command succeeded before sending the second.
Command names are case-insensitive but traditionally written in uppercase.
.Pp
Blank lines are silently ignored.
The client is not required to close the connection in any way besides disconnecting from the socket; it is also not required to wait for
.Ql ACK
or
.Ql NACK
responses from the server.
Any responses that would have been written after the socket is closed will be silently dropped.
.Ss Available commands
.Bl -tag -width Ds
.It Ic CMDS
Returns a space-separated, uppercase list of commands the daemon understands.
Does not return
.Ql NACK .
.It Ic VERSION
Returns the version of the running daemon's master process.
Does not return
.Ql NACK .
.It Ic RESTART
Triggers a zero-downtime restart.
Receipt of an
.Ql ACK
does not indicate that the restart has completed; merely that it has been queued for processing.
.Ql NACK
reason strings may be one of
.Ql no workers
if there aren't enough workers available;
.Ql bad driver
if zero-downtime restarts aren't available on the current Databank driver;
.Ql aborted restart
if a previous restart attempt failed;
.Ql restart in flight
if there's already an ongoing restart attempt; or
.Ql incompatibility
if the new version indicates an incompatibility.
If the reason string is
.Ql aborted restart ,
the program should warn the user to restart pump.io as soon as possible.
.Pp
Other reason strings may be added to this command in the future.
.El
.Sh FILES
By default the control socket is created owner read-write at
.Pa /var/run/pump.socket .
The owner will depend on whoever started the daemon.
.Pp
The location can be influenced by the
{'fraction_non_alphanumeric': 0.05297055730809674, 'fraction_numerical': 0.004600420609884332, 'mean_word_length': 3.973202614379085, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1021161', 'n_tokens_mistral': 2102, 'n_tokens_neox': 1994, 'n_words': 1205}