tii

Tcl-based suite for working with ii/idec protocol
git clone git://git.luxferre.top/tii.git
Log | Files | Refs | README

README (6991B)


      1 tii: a Tcl-based suite for working with ii/IDEC protocol
      2 ========================================================
      3 This suite implements the client side of ii and (partially) IDEC protocols of
      4 distributed, cross-platform, text-based communication (a FIDOnet successor, so
      5 to speak). See ii-doc.txt for the protocol documentation.
      6 
      7 The tii suite requires at least Tcl 8.6 to run. Running it inside starpacks is
      8 possible but not recommended.
      9 
     10 The tii distribution consists of the following parts:
     11 
     12 * tiifetch.tcl: the core ii/IDEC message fetching library and CLI utility
     13 * tiipost.tcl: the core ii/IDEC message posting library and CLI utility
     14 * tiiview.tcl: the CLI viewer of the fetched ii/IDEC messages and conferences
     15 * tii.db: the SQLite3 database that contains all messages and echo lists
     16 * config.txt: the set of parameters for all HTTP requests by the tii scripts
     17 * stations.txt: the list of stations to be auto-fetched by tiifetch when none
     18   of its command-line parameters is passed (not included in the repo)
     19 * auth.txt: the list of station/authstring mappings to be used by tiipost when
     20   posting messages to a particular station (not included in the repo)
     21 * tiix.tcl: the GUI ii/IDEC viewer that also leverages tiifetch and tiipost to
     22   provide fetching and posting functionality
     23 
     24 Readiness status
     25 ----------------
     26 * tiifetch.tcl: ready/tested
     27 * tiipost.tcl: ready/tested
     28 * tiiview.tcl: ready/tested
     29 * tii.db (format): ready/tested
     30 * config.txt (format/fields): ready/tested
     31 * stations.txt (format): ready/tested
     32 * auth.txt (format): ready/tested
     33 * tiix.tcl: ready/testing
     34 * Overall status: basically ready, bugfixing in progress
     35 
     36 Usage
     37 -----
     38 This section is a work in progress and will be updated as more components are
     39 developed.
     40 
     41 ### Fetching the messages (tiifetch.tcl): ###
     42 
     43 tclsh tiifetch.tcl [station_url] [echos] [dbfile]
     44 
     45 This command will fetch all messages into the dbfile ("tii.db" in the script
     46 dir by default) from the station_url (can be empty, see below) based on the
     47 echo conference names (can be delimited with slash /, comma (,) or semicolon
     48 (;)) and create the corresponding file structure if it's missing.
     49 
     50 Fetching is supported for the following station URL schemes and protocols:
     51 
     52 * HTTP (http://)
     53 * HTTPS (https://)
     54 * Gopher (gopher://)
     55 * Gopher over TLS (gophers://)
     56 * Finger (finger://)
     57 * Nex (nex://)
     58 * Spartan (spartan://)
     59 * Gemini (gemini://)
     60 
     61 If the station_url parameter is empty or no parameters are passed at all,
     62 tiifetch.tcl will look for a file called stations.txt that lists (each on a
     63 new line) all the station URLs to sync from and the amount of IDs that can
     64 be fetched from a particular station with a single GET request (this amount
     65 can be 12 or more):
     66 
     67 https://url1 389
     68 gemini://url2 24
     69 http://url3 12
     70 
     71 Messages from all listed stations will be merged into the same echo database.
     72 You also can comment out a station to temporarily stop fetching from it by
     73 prepending the # sign.
     74 
     75 ### Viewing the messages from CLI (tiiview.tcl): ###
     76 
     77 tclsh tiiview.tcl [echo_name] [filter_string] [line_width] [dbfile]
     78 
     79 If the echo_name parameter is passed, this command will write all formatted
     80 messages from the coresponding echo conference to the standard output.
     81 You should pipe this message stream to your $PAGER terminal application, like
     82 less or most. The messages will be formatted according to the filter_string
     83 format (see below). If the filter string is empty or omitted, the messages
     84 will appear in the exact order their IDs appear in the echo conference file.
     85 
     86 If the echo_name parameter is empty or no parameters are passed at all, this
     87 command will output the list of echo conferences registered in the dbdir.
     88 The conference list will be alphabetically ordered and the filter_string will
     89 have no effect at all if you pass it.
     90 
     91 If the line_width parameter is omitted, the text reflows to 80 chars per line.
     92 
     93 If the dbfile is omitted, it defaults to "tii.db" in the script directory.
     94 
     95 This component is fully offline and can only work with a compatible message
     96 database that tiifetch.tcl can generate.
     97 
     98 The filter string can take one of the following basic forms:
     99 
    100 * [number]: only take [number] messages from the head (start) of the list
    101 * r[number]: same but output messages from newest to oldest in the list
    102 
    103 If [number] is 0 then it means no message limit.
    104 The reverse operation is always done after limiting the results.
    105 
    106 e.g. r50 will output 50 newest messages in the conference, starting from the
    107 most recent one. The default basic value is h0, so no filter applied will mean
    108 outputting all messages from the oldest to the newest.
    109 
    110 You can extend the basic form by appending a search regular expression to it,
    111 like this: [form]/[regex]. Note that the regex always applies AFTER the basic
    112 filtering has been done. Also note that the search is done within all fields
    113 of the message. E.g. h100/retro will find the retro-themed messages among the
    114 first 100 of them.
    115 
    116 ### Posting the messages from CLI (tiipost.tcl): ###
    117 
    118 echo my_post_text | tiipost.tcl station_root_url echo_name msgto subj [repto]
    119 
    120 The tiipost.tcl script accepts the message body from the standard input. The
    121 body must be provided in UTF-8 encoding and all command line parameters except
    122 [repto] (reply-to ID) are mandatory.
    123 
    124 The script will look for the auth.txt file in its directory, with the format:
    125 
    126 station_url_1 password1
    127 station_url_2 password2
    128 ...
    129 
    130 If the station root URL matches one of the lines in auth.txt, it automatically
    131 will use the password as the authstring when posting to the station.
    132 
    133 On success, tiipost.tcl will output a message that starts with "Success", in
    134 case of an error the line will start with "Error". The server-side description
    135 will follow this success or error status.
    136 
    137 As of now, posting is only supported for HTTP/HTTPS station URLs.
    138 
    139 HTTP client configuration
    140 -------------------------
    141 For both fetching and posting, you can configure several values in the config
    142 file (config.txt in the script directory, the example is included in the repo)
    143 that will allow you to set HTTP proxy and override the user agent. As of now,
    144 the file is a Tcl dictionary (`key "value"`) and has the following fields:
    145 
    146 * useragent: the user agent string to set for all HTTP requests
    147 * proxyhost: the HTTP proxy hostname to use (if empty or omitted, the scripts
    148   will connect directly)
    149 * proxyport: the HTTP port to use on the proxy (only effective if proxyhost is
    150   set to a non-empty string)
    151 * net_timeout: the timeout (in milliseconds) for all network requests
    152 
    153 Any of the fields can be omitted, as well as the file itself.
    154 You can also use torsocks with any script invocation in order to fully cloak
    155 your originating IP address.
    156 
    157 
    158 FAQ
    159 ---
    160 - Does tii implement any IDEC extensions?
    161 
    162 Only one: fetching list.txt from the station to get the entire list of echo
    163 conferences served by this station. This is something that the original ii
    164 spec did not support.
    165 
    166 
    167 Credits
    168 -------
    169 Created by Luxferre in 2024, released into public domain with no warranties.
    170