2022-06-09 01:25:45 +00:00
# Syndicate utils
2024-01-08 18:48:04 +00:00
## Syndesizer
2024-01-09 09:35:19 +00:00
A Syndicate multitool that includes a number of different actors that become active via configuration.
Think of it as a Busybox for Syndicate, if Busybox was created before POSIX.
2024-01-08 18:48:04 +00:00
Whether you use a single instance for many protocols or many specialized instances is up to you.
2024-01-08 19:42:46 +00:00
### Cache
Observes patterns and reässert the values captured for a given lifetime. Takes the argument `<cache { dataspace: #!any lifetime: float }>` . The lifetime of a cache counts down from moment a value is asserted.
Example configuration:
```
? < nixspace ? nixspace > [
; Require the nix_actor during observations.
?nixspace> ? < Observe < rec eval _> _ > [
$config < require-service < daemon nix_actor > > ]
?nixspace> ? < Observe < rec realise _> _ > [
$config < require-service < daemon nix_actor > > ]
; Cache anything captured by observers in the $nixspace for an hour.
; The nix_actor is not required during caching.
$config < require-service < daemon syndesizer > >
$config ? < service-object < daemon syndesizer > ?cap> [
$cap < cache { dataspace: $ nixspace lifetime: 3600 . 0 } > ]
]
```
2024-04-05 13:09:55 +00:00
2024-01-09 18:49:54 +00:00
### File System Usage
Summarize the size of file-system directory. Equivalent to `du -s -b` .
Query the size of a directory in bytes by observing `<file-system-usage "/SOME/PATH" ?size>` .
```
# Configuration example
? < exposed-dataspace ? ds > [
< require-service < daemon syndesizer > >
? < service-object < daemon syndesizer > ?cap> [
$cap < file-system-usage { dataspace: $ ds } >
]
]
```
2024-01-08 19:42:46 +00:00
2024-01-08 19:14:33 +00:00
### JSON Socket Translator
Communicate with sockets that send and receive lines of JSON using `<send …>` and `<recv …>` messages.
Do not send messages into the dataspace configure with `<json-socket-translator …>` until `<connected @socketPath string>` is asserted.
```
# MPV configuration example
< require-service < daemon mpv-server > >
< daemon mpv-server {
argv: [
"/run/current-system/sw/bin/mpv"
"--really-quiet"
"--idle=yes"
"--no-audio-display"
"--input-ipc-server=/run/user/1000/mpv.sock"
"--volume=75"
]
protocol: none
}>
let ?mpvSpace = dataspace
? < service-state < daemon mpv-server > ready> [
< require-service < daemon syndesizer > >
? < service-object < daemon syndesizer > ?cap> [
$cap < json-socket-translator {
dataspace: $mpvSpace
2024-04-05 13:16:03 +00:00
socket: < unix " / run / user / 1000 / mpv . sock " >
2024-01-08 19:14:33 +00:00
}>
]
]
$mpvSpace [
# announce the dataspace when the translator is connected
? < connected $ socketPath > [
$config < mpv $ mpvSpace >
$config < bind < ref { oid: " mpv " key: #x "" } > $mpvSpace #f >
]
# translate < play-file … > to an MPV command
?? < play-file ? file > [
! < send { " command " : [ " loadfile " $ file " append-play " ] } >
]
# clear the playlist on idle so it doesn't grow indefinitely
?? < recv { " event " : " idle " } > [
! < send { " command " : [ " playlist-clear " ] } >
]
]
```
2024-01-08 20:10:55 +00:00
### JSON Stdio Translator
Executes a command, parses its JSON output, converts to record `<recv @jsonData any>` , and publishes and messages it to a dataspace.
```
# Configuration example
< require-service < daemon syndesizer > >
let ?ds = dataspace
< bind < ref { oid: " syndicate " key: #x ""} > $ds #f >
? < service-object < daemon syndesizer > ?cap> [
$cap < json-stdio-translator {
argv: [
"yt-dlp"
"--dump-json"
"https://youtu.be/RR9GkEXDvog"
]
dataspace: $ds
}>
]
```
2024-01-14 10:52:17 +00:00
### Pulse proxy
A proxy actor that passes assertions and messages to a configured capability but only asserts observations on a a periodic pulse.
This can be used to implement polling behavior.
```
# Example config
let ?ds = dataspace
< require-service < daemon syndesizer > >
? < service-object < daemon syndesizer > ?cap> [
$cap < pulse { dataspace: $ ds } >
]
$ds ? < pulse 3600 . 0 ? proxy > [
$proxy ? < assertion-updated-hourly ? value > [
$log ! < log " - " { assertion-updated-hourly: $ value } >
]
]
```
2024-01-09 11:21:30 +00:00
### SQLite
Readonly access to SQLite databases. Asserts rows as records in response to SQL query assertions. Dynamic updates are not implemented.
Can be disabled by passing `--define:withSqlite=no` to the Nim compiler.
```
# Configuration example
< require-service < daemon syndesizer > >
let ?sqlspace = dataspace
? < service-object < daemon syndesizer > ?cap> [
$cap < sqlite {
dataspace: $sqlspace
database: "/var/db/example.db"
}>
]
2024-01-16 18:21:52 +00:00
let ?tuplespace = dataspace
2024-01-18 10:58:17 +00:00
$sqlspace < query " SELECT id , name FROM stuff " $ tuplespace >
2024-01-09 11:21:30 +00:00
2024-01-18 10:58:17 +00:00
$tuplespace ? [?id ?name] [
2024-01-09 11:21:30 +00:00
$log ! < log " - " { row: < example-row $ id $ name > }>
]
```
2024-01-20 13:28:36 +00:00
### XML translator
Translates between Preserves and XML according to the [Conventions for Common Data Types ](https://preserves.dev/conventions.html ).
Examples:
- `<xml-translation "<foo a=\"1\"> <bar>hello world!</bar></foo>" <foo {"a": 1}<bar "hello world!">>>`
- `<xml-translation "" [#t #f]>`
- `<xml-translation "<<</>>" #f>`
```
# Configuration example
? < sharedspace ? ds > [
$ds ? < Observe < rec xml-translation _> _ > $config [
$config < require-service < daemon syndesizer > >
$config ? < service-object < daemon syndesizer > ?cap> [
$cap < xml-translator { dataspace: $ ds } >
]
]
]
```
2024-01-09 09:35:19 +00:00
2024-01-08 19:42:46 +00:00
---
2023-11-08 10:50:30 +00:00
2023-08-25 09:14:13 +00:00
## mintsturdyref
A utility for minting [Sturdyrefs ](https://synit.org/book/operation/builtin/gatekeeper.html#sturdyrefs ).
2023-11-29 20:22:58 +00:00
## mount_actor
Actor for mounting filesystems on Linux.
Sample Syndicate server script:
```
# Assert a file-system we want to mount.
< mount " / dev / sda3 " " / boot " " vfat " >
# Transform mount assertions into mount status observations.
? < mount ? source ? target ? fs > [
? < mount $ source $ target $ fs _ > [ ]
]
# Assert mounting succeded.
? < mount _ ?target _ #t > [
< service-state < mountpoint $ target > ready>
]
# Assert mount failed.
? < mount _ ?target _ < failure _ > > [
< service-state < mountpoint $ target > failed>
]
# Assert the details into the machine dataspace.
? < machine-dataspace ? machine > [
$config ? < mount ? source ? target ? fs ? status > [
$machine < mount $ source $ target $ fs $ status >
]
]
# Require the mount_actor daemon.
< require-service < daemon mount_actor > >
< daemon mount_actor {
argv: ["/home/emery/src/bin/mount_actor"]
protocol: application/syndicate
}>
# Pass the daemon the config dataspace.
? < service-object < daemon mount_actor > ?cap> [
$cap { dataspace: $config }
]
```
2022-06-09 17:24:02 +00:00
## msg
2023-10-21 18:03:11 +00:00
A utility that sends messages to `$SYNDICATE_ROUTE` .
2023-05-18 16:48:50 +00:00
2024-03-28 13:48:30 +00:00
## PostgreSQL
Readonly access to PostgreSQL databases. Asserts rows as records in response to SQL query assertions. Dynamic updates are not implemented.
Can be disabled by passing `--define:withPostgre=no` to the Nim compiler.
```
# Configuration example
< require-service < daemon postgre_actor > >
let ?sqlspace = dataspace
? < service-object < daemon postgre_actor > ?cap> [
$cap < postgre {
dataspace: $sqlspace
connection: [
["host" "example.com"]
["dbname" "foobar"]
["user" "hackme"]
]
}>
]
let ?tuplespace = dataspace
$sqlspace < query " SELECT id , name FROM stuff " $ tuplespace >
$tuplespace ? [?id ?name] [
$log ! < log " - " { row: < example-row $ id $ name > }>
]
```
2023-05-18 16:48:50 +00:00
## 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.
2023-08-24 08:20:33 +00:00
2024-03-28 13:48:30 +00:00
## SQLite
Readonly access to SQLite databases. Asserts rows as records in response to SQL query assertions. Dynamic updates are not implemented.
Can be disabled by passing `--define:withSqlite=no` to the Nim compiler.
```
# Configuration example
< require-service < daemon sqlite_actor > >
let ?sqlspace = dataspace
? < service-object < daemon sqlite_actor > ?cap> [
$cap < sqlite {
dataspace: $sqlspace
database: "/var/db/example.db"
}>
]
let ?tuplespace = dataspace
$sqlspace < query " SELECT id , name FROM stuff " $ tuplespace >
$tuplespace ? [?id ?name] [
$log ! < log " - " { row: < example-row $ id $ name > }>
]
```
2023-08-24 08:20:33 +00:00
2023-08-25 08:36:57 +00:00
## syndump
2023-08-24 08:20:33 +00:00
2023-10-21 18:03:11 +00:00
Utility for printing assertions and messages. Parses the command-line arguments as a pattern, connects a dataspace via `$SYNDICATE_ROUTE` , and writes observations to standard-output. Published assertions are prefixed by the `+` character, retractions by `-` , and messages by `!` .
2023-08-24 08:20:33 +00:00
Example
```sh
2023-08-25 08:36:57 +00:00
# Print patterns in use, filter down with AWK to only the published patterns.
$ FS=':' syndump '< Observe ? _ > ' | awk -F : '/^+/ { print $2 }'
2023-08-24 08:20:33 +00:00
```
2024-03-28 13:48:30 +00:00
## XSLT processor
Perform XML stylesheet transformations. For a given textual XSLT stylesheet and a textual XML document generate an abstract XML document in Preserves form. Inputs may be XML text or paths to XML files.
```
# Configuration example
let ?ds = dataspace
$ds [
? < xslt-transform " / stylesheet . xls " " / doc . xml " ? output > [
? < xml-translation ? text $ output > [
$log ! < log " - " { xslt-output: $ text } >
]
]
]
< require-service < daemon xslt_actor > >
? < service-object < daemon xslt_actor > ?cap> $cap [
< xml-translator { dataspace: $ ds } >
< xslt { dataspace: $ ds } >
]
```