<commit_before>/*
Package adminsock provides a Unix domain socket -- with builtin
request dispatch -- for administration of a daemon.

COMMAND DISPATCH

Consider this example, showing an instance of adminsock being setup as
an echo server.

    func hollaback(s []string) ([]byte, error){
        // a trivial echo server implementation
        return []byte(strings.Join(s, " ")), nil
    }
    
    func set_things_up() {
        // populate a dispatch table
        d := make(adminsock.Dispatch)
        d["echo"] = hollaback
        
        // instantiate a socket (/tmp/echosock or /var/run/echosock),
        // with no connection timeout, which will generate maximal
        // informational messages
        as, err := adminsock.New("echosock", d, 0, adminsock.All)
        ...
    }

A function is defined for each request which adminsock will handle.
Here there is just the one, hollaback().

These functions are added to an instance of adminsock.Dispatch, which
is passed to adminsock.New(). Functions added to the Dispatch map must
have the signature

    func ([]string) ([]byte, error)

The Dispatch map keys form the command set that the instance of
adminsock understands. They are matched against the first word of text
being read from the socket.

Given the above example, if

    echo foo bar baz

was sent to the socket, then hollaback() would be invoked with:

    []string{"foo", "bar", "baz"}

And it would return:

    []byte("foo bar baz"), nil

If error is nil (as it is here), then the returned byteslice will be
written to the socket as a response.

If error is non-nil, then a message about an internal error having
occurred is sent (no program state is exposed to the client).

If the first word of a request does not match a key in the Dispatch
map, an unrecognized command error will be sent. This message will
contain a list of all known commands. It is left to the user to
provide more comprehensive help.

MONITORING

Servers are typically event-driven and adminsock is designed around
this assumption. Once instantiated, all that needs to be done is
monitoring the Msgr channel. Somewhere in your code, there should be
something like:

    select {
    case msg := <-as.Msgr:
        // Handle adminsock notifications here.
    case your_other_stuff:
        ...
    }

Msgr receives instances of Msg, each of which contains a connection
number, a request number, a status code, a textual description, and an
error.

The connection and request numbers (Msg.Conn, Msg.Req) are included
solely for your client tracking/logging use.

As with HTTP, the status code tells you both generally and
specifically what has occured.
<commit_msg>better doc<commit_after>/*
Package adminsock provides a Unix domain socket -- with builtin
request dispatch -- for administration of a daemon.

COMMAND DISPATCH

Consider this example, showing an instance of adminsock being setup as
an echo server.

    func hollaback(s []string) ([]byte, error){
        // a trivial echo server implementation
        return []byte(strings.Join(s, " ")), nil
    }
    
    func set_things_up() {
        // populate a dispatch table
        d := make(adminsock.Dispatch)
        d["echo"] = hollaback
        
        // instantiate a socket (/tmp/echosock or /var/run/echosock),
        // with no connection timeout, which will generate maximal
        // informational messages
        as, err := adminsock.New("echosock", d, 0, adminsock.All)
        ...
    }

A function is defined for each request which adminsock will handle.
Here there is just the one, hollaback().

These functions are added to an instance of adminsock.Dispatch, which
is passed to adminsock.New(). Functions added to the Dispatch map must
have the signature

    func ([]string) ([]byte, error)

The Dispatch map keys form the command set that the instance of
adminsock understands. Here there is just the one, "echo". They are
matched against the first word each request read from the socket.

If the first word of a request does not match a key in the Dispatch
map, an unrecognized command error will be sent. This message will
contain a list of all known commands. It is left to the user to
provide more comprehensive help.

Continuing from the above example, if

    echo foo bar baz

was sent to the socket, then hollaback() would be invoked with:

    []string{"foo", "bar", "baz"}

And it would return:

    []byte("foo bar baz"), nil

If error is nil (as it is here), then the returned byteslice will be
written to the socket as a response.

If error is non-nil, then a message about an internal error having
occurred is sent (no program state is exposed to the client).

MONITORING

Servers are typically event-driven and adminsock is designed around
this assumption. Once instantiated, all that needs to be done is
monitoring the Msgr channel. Somewhere in your code, there should be
something like:

    select {
    case msg := <-as.Msgr:
        // Handle adminsock notifications here.
    case your_other_stuff:
        ...
    }

Msgr receives instances of Msg, each of which contains a connection
number, a request number, a status code, a textual description, and an
error.

The connection and request numbers (Msg.Conn, Msg.Req) are included
solely for your client tracking/logging use.

As with HTTP, the status code tells you both generally and
specifically what has occured.

{'fraction_non_alphanumeric': 0.06691449814126393, 'fraction_numerical': 0.0003717472118959108, 'mean_word_length': 3.243690851735016, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, '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': '1471333', 'n_tokens_mistral': 1485, 'n_tokens_neox': 1430, 'n_words': 746}