syndicate_utils/README.md

# Syndicate utils

## json_translator

Wrapper that executes a command, parses its JSON output, converts to Preserves record `<recv @jsonData any>`, and publishes and messages to its initial dataspace.

## json_socket_translator

Utility to communicate with sockets that send and receive lines of JSON using `<send …>` and `<recv …>` messages. Compatible with [mpv](https://mpv.io/), see [mpv.config-example.pr](./mpv.config-example.pr).

Do not send messages immediately to the dataspace passed `json_socket_translator`, wait until it asserts `<connected @socketPath string>`.

## mintsturdyref

A utility for minting [Sturdyrefs](https://synit.org/book/operation/builtin/gatekeeper.html#sturdyrefs).

## msg

A utility that sends a message to `$SYNDICATE_SOCK` in the form `<ARGV0 ARG1 … ARGVn>`.
The `$SYNDICATE_STEP` variables sets the SturdyRef capability with a default to the SturdyRef generated by `<ref { oid: "syndicate" key: #x"" }>`.


## net_mapper

Publishes ICMP packet round-trip-times. See [net_mapper.prs](./net_mapper.prs) for a protocol description. [Source](./src/net_mapper.nim).

Example script:
```
? <machine-dataspace ?machine> [
  $machine ? <rtt "10.0.33.136" ?min ?avg ?max> [
    $log ! <log "-" { ping: { min: $min avg: $avg max: $max } }>
  ]

  $config [
    <require-service <daemon net_mapper>>
    <daemon net_mapper {
      argv: ["/bin/net_mapper"]
      protocol: application/syndicate
    }>
    ? <service-object <daemon net_mapper> ?cap> [
      $cap { dataspace: $machine }
    ]
  ]
]
```

## preserve_process_environment

This utility serializes it's process environment to Preserves and prints it to stdout.
It can be used to feed the environment variables of a nested child of the Syndicate server back to the server. For example, to retreive the environmental variables that a desktop manager passed on to its children.


## syndump

Utility for printing assertions and messages. Parses the command-line arguments as a pattern, connects to `$SYNDICATE_SOCK`, authenticates with the SturdyRef at `$SYNDICATE_STEP`, and writes observations to standard-output. Published assertions are prefixed by the `+` character, retractions by `-`, and messages by `!`.

Example
```sh
# Print patterns in use, filter down with AWK to only the published patterns.
$ FS=':' syndump '<Observe ? _>' | awk -F : '/^+/ { print $2 }'
```