Idefix is a CLI PHP script that listens for notifications coming to a defineable set of Mastodon accounts, making every account in the set act as an on-demand follow/unfollow bot.

pezcurrel fe219d49ba Updated to help text as in 9b788c2 commit 2 weeks ago
README.md fe219d49ba Updated to help text as in 9b788c2 commit 2 weeks ago
idefix 9b788c2b93 Updated help text 2 weeks ago

README.md

[[[  SYNOPSIS  ]]]

idefix [options] <project directory>

[[[  DESCRIPTION  ]]]

This is idefix v0.9.14, a CLI PHP script that listens for notifications coming
to a defineable set of Mastodon accounts (see section «BOTS CONFIG FILE»
below), making every account in the set act as an on-demand follow/unfollow
bot (let’s call it an Idefix account, from now on) that can manage «requests»
from any non-bot account residing on instances among those for which an Idefix
account is defined in the set; in every other case the request will be ignored
and an error toot will be sent in reply.
This gives users of the instances for which a Idefix account is defined in the
set, particularly new ones, the possibility to make themselves followed by at
least one account (the Idefix account) on any other instance in the set, thus
ensuring their public toots will appear on the corresponding «federated
timeline», helping them to reach other users outside their instance, if they
want to.
«Requests» can be simple follow requests, in which case the user will be
followed by all the Idefix accounts in the set, or they can be sent in
«command toots» whose content must follow a simple command syntax (see the
«COMMANDS» section towards the end of this help text); the addressed Idefix
account will answer to a «command toot» with a toot with the same visibility
as the received one; a «command toot» can be written in english or italian
language; the addressed Idefix account will answer in italian to toots which
have their language set to italian, and in english to all the others.
Idefix will also periodically post a configurable public announcement toot, in
turn, from each Idefix account in the set; the periodicity (that is the
interval to wait for before sending an announcement toot from the next Idefix
account in the set) is configurable, and announcement toots can be disabled
altogether (see the «--annint» option description in the «OPTIONS» section
below). These announcement toots will be delivered to all the federated
timelines of all the instances for which a Idefix account is defined in the
set, because idefix makes sure that each defined Idefix account follows each
other.
Idefix can be stopped at any time with a SIGTERM, SIGHUP or SIGINT (ctrl+c)
signal without problems: it will nicely shut down and, on subsequent run, it
will manage only those notifications which it didn’t manage before.
In order for idefix to work, an existing «project directory» has to be passed
as an argument to it.

[[[  BOTS CONFIG FILE  ]]]

The «project directory» must contain a file named «idefix.botsconf». This file
should contain the accounts definitions (at least one), one definition for
each line (empty lines and lines with an «#» character on their first column
will be ignored).
Each account definition should follow this syntax:

<account> <domain handle> <max toot length> <token>

- «account» should be the full Mastodon address of the bot’s account;
- «domain handle» should be an handle for the domain the bot’s account resides
on; for example, the handle for «mastodon.cisti.org» could be «cisti» (or
anything else); handles can be used by users in «command toots» (see the
«COMMANDS» section below) and are used in some template types (see the
«TEMPLATES» section below);
- «max toot length» should be the maximum length a toot can have on the
instance the bot’s account resides on; this value will be used to check each
toot (and each profile’s «bio», when «--setprof» option is used: see the
«OPTIONS» section below) before it is sent;
- «token» should be the access token of an «application» that has already been
created on the account (via «Preferences» -> «Development» -> «New
application», in the official Mastodon web frontend) with at least «read»,
«write» and «follow» privileges.

--- Example «idefix.botsconf» file ---
# These lines will be ignored, since they are commented out by a «#» at their
# beginning; next line will be ignored too, since it’s empty.

follbot@amarone.net amarone 500 xA9kZe9zB6EgtjsW5EVr4axYWW46c1TPC-RpQhnkAvw
follbot@nebbiolo.org nebbiolo 550 7fne902mc0954mi2ollWMNfasdf6aposdfADF9MFN12
follbot@ostrugo.info ostrugo 840 0XJfrQ2C9ddzB9H3brTcwt-afo3ZOpTN4jmZbQrPoO8
follbot@dolcetto.fail dolcetto 500 Gm3lvO4LxwaXkmhW_q6VSvcBkj_05N0bvJc0TlwnTkw
follbot@barbera.info barbera 600 l8r3kQynViz2BHw5NKBw7GajnkrSCDeqTI58KUfs6X2
--- End of example «idefix.botsconf» file ---

[[[  OPTIONS  ]]]

Options can be specified on command line and in a «idefix.conf» file inside
the «project directory» (see the «CONFIG FILE» section below). Options
specified on command line always supersede those specified in the config file.

-s, --sleepsecs <amount of seconds>
 Sets the amount of seconds idefix will pause for after checking for new
 notifications on all defined accounts.
 DEFAULT: 10 seconds.

-a, --annint <time specification>
 Sets the interval for periodic announcement toot sending.
 EXAMPLE: «idefix -a 1d,10h,12m,30s» will set the interval to 1 day,
 10 hours, 12 minutes and 30 seconds (123150 seconds).
 Setting this option to the «never» special value will completely disable
 announcements.
 DEFAULT: 6 hours.

-b, --botsmasteraddr <bots’ master address>
 Sets the «bots’ master» address. It has a corresponding
 «%bots_master_address%» template keyword that can be used in any template,
 see the «TEMPLATES» section below.
 DEFAULT: «obelix@livellosegreto.it».

-e, --enhelpurl <url>
 Sets the url for english help (it is used in some reply toots and has
 a corresponding template keyword, «%en_help_url%»; see the «TEMPLATES»
 section below).
 DEFAULT: «https://git.lattuga.net/pongrebio/idefix/wiki/Help».

-i, --ithelpurl <url>
 Sets the url for italian help (it is used in some reply toots and has
 a corresponding template keyword, «%it_help_url%»; see the «TEMPLATES»
 section below).
 DEFAULT: «https://git.lattuga.net/pongrebio/idefix/wiki/Guida».

-p, --setprof <«builtin»|profile configuration file name>
 Sets every defined bot account’s profile «bot» flag, «bio» field and metadata
 «key-value» pairs according to a profile configuration, then exit. If the
 «builtin» special value is passed, these profile’s properties will be set
 according to the builtin configuration (see below), otherwise they will be
 set according to the configuration defined in a file inside the defined
 «project directory», with «profile configuration file name» and with
 «.profconf» extension. For example, if you created a profile configuration
 file named «my.profconf» in the «project directory», you could pass «my» as
 «profile configuration file name» to «--setprof».
 --- Example profile configuration file ---
 bot=true
 bio=Hello, I’m %current_bot_address%, managed by %bots_master_address%.
 md=Bots master : %bots_master_profile_url%
 md=Help : %en_help_url%
 --- End of example profile configuration file ---
 The profile configuration file must define a «bot» entry and a «bio» entry;
 it can also define one ore more «md» entries. The «bot» entry has to be set
 to a boolean value (true/t/yes/y/1=true, false/f/no/n/0=false); the «bio»
 entry has to be set to a bio text, that will be treated as a template (see
 section «TEMPLATES» below); each defined «md» entry can be set to
 «key : value» pairs (that is, «value» must be separated from «key» by a « : »
 string; both «key» and «value» text will be treated as templates); otherwise
 it can be set to the «delete» special expression. If no «md» entry is
 defined, all the metadata «key-value» pairs on every defined bot account’s
 profile will be left untouched; if one or more «md» entries are defined, all
 current metadata «key-value» pairs on every profile will be deleted and the
 defined ones will be set; if *any* defined «md» entry is set to «delete», all
 the profiles’ metadata fields will be deleted.
 --- Builtin profile configuration ---
 bot=true
 bio=Woof! I’m Idefix, an on-demand follow bot. If your account is on\
 %bots_domains-or%, and if you want me to follow you from all these\
 instances, to make sure your public toots will reach their federated\
 timelines, just follow me and I’ll follow you back. To make me stop\
 following you from all these instances, just send me a toot with the command\
 «unfollow me». For more info see %en_help_url% ;-)
 md=Bots master : %bots_master_profile_url%
 --- End of builtin profile configuration ---

-U, --unfollowall
 Unfollow *every* user’s account from *every* defined bot account, then exit.
 Note that the defined bot accounts won’t unfollow each other.

-f, --force <boolean: true/t/yes/y/1=true, false/f/no/n/0=false>
 If set to true, it forces execution even if a lockfile exists in «project
 directory».
 DEFAULT: false.

-t, --timeout <amount of seconds (float)>
 Sets the timeout for all http operations.
 DEFAULT: 8 seconds.

-l, --logverb <«debug»|«info»|«warning»|«error»>
 Sets the verbosity of output to the logfile.
 DEFAULT: «info».

-T, --termverb <«debug»|«info»|«warning»|«error»>
 Sets the verbosity of output to the terminal.
 DEFAULT: «info».

-h, --help
 Show this help text and exit.

[[[  CONFIG FILE  ]]]

The «project directory» can contain a file named «idefix.conf» with
«option=argument» pairs, one for each line. «Option» can be any option listed
in the «OPTIONS» section above, in its long form, except «help», «setprof» and
«unfollowall»; «argument» must be a valid argument for the option. Remember
that any option specified on command line supersede those specified in the
config file.

--- Example «idefix.conf» file ---
# These lines will be ignored, since they are commented out by a «#» at their
# beginning; next line will be ignored too, since it’s empty.

sleepsecs=20
annint=3h
enhelpurl=https://x.org/mybot/help_en
ithelpurl=https://x.org/mybot/help_it
--- End of example «idefix.conf» file ---

[[[  TEMPLATES  ]]]

You can customize any template idefix uses to build its output by creating a
file named «idefix.templates» in the «project directory».
Currently defined templates are:

--- Templates list ---
[ Template ]: announcement
[ Description ]: The announcement toot.
[ Default ]: Woof! I’m Idefix, an on-demand follow bot. If your account is on
%bots_domains-or%, and if you want me to follow you from all these instances,
to make sure your public toots will reach their federated timelines, just
follow me and I’ll follow you back. To make me stop following you from all
these instances, just send me a toot with the command «unfollow me». For more
info see %en_help_url% ;-)

[ Template ]: generic_salutation-en
[ Description ]: This text is the generic salutation used at the beginning of
any toot in reply to any request (english version); it *must* contain
«@%sender_address», otherwise all reply toots will be sent to the void ;-).
[ Default ]: Woof @%sender_address%

[ Template ]: generic_salutation-it
[ Description ]: This text is the generic salutation used at the beginning of
any toot in reply to any request (italian version); it *must* contain
«@%sender_address», otherwise all reply toots will be sent to the void ;-).
[ Default ]: Bau @%sender_address%

[ Template ]: unsupported_instance-en
[ Description ]: This text is the final part of the toot that is sent in reply
to any request coming from an unsupported instance (english version).
[ Default ]: I can’t consider your request since you are on an unsupported
instance. Instances I support are %bots_domains-and%.

[ Template ]: unsupported_instance-it
[ Description ]: This text is the final part of the toot that is sent in reply
to any request coming from an unsupported instance (italian version).
[ Default ]: non posso considerare la tua richiesta perché viene da un’istanza
non supportata. Le istanze che supporto sono %bots_domains-e%.

[ Template ]: not_from_other_bots-en
[ Description ]: This text is the final part of the toot that is sent in reply
to any request coming from an account that has the «bot» profile property
enabled (english version).
[ Default ]: I’m sorry but I can’t consider requests coming from other bot
accounts.

[ Template ]: not_from_other_bots-it
[ Description ]: This text is the final part of the toot that is sent in reply
to any request coming from an account that has the «bot» profile property
enabled (italian version).
[ Default ]: mi spiace ma non posso considerare le richieste da altri account
bot.

[ Template ]: follow_success-en
[ Description ]: This text is the «success» part of the toot that is sent in
reply to a follow request toot (english version).
[ Default ]: I’m following you from

[ Template ]: follow_success-it
[ Description ]: This text is the «success» part of the toot that is sent in
reply to a follow request (italian version).
[ Default ]: ti sto seguendo da

[ Template ]: follow_failure-en
[ Description ]: This text is the «failure» part of the toot that is sent in
reply to a follow request (english version).
[ Default ]: due to technical problems I could not follow you from

[ Template ]: follow_failure-it
[ Description ]: This text is the «failure» part of the toot that is sent in
reply to a follow request (italian version).
[ Default ]: a causa di problemi tecnici non sono riuscito a seguirti da

[ Template ]: unfollow_success-en
[ Description ]: This text is the «success» part of the toot that is sent in
reply to an unfollow request (english version).
[ Default ]: I am no longer following you from

[ Template ]: unfollow_success-it
[ Description ]: This text is the «failure» part of the toot that is sent in
reply to an unfollow request (italian version).
[ Default ]: non ti sto più seguendo da

[ Template ]: unfollow_failure-en
[ Description ]: This text is the «failure» part of the toot that is sent in
reply to an unfollow request (english version).
[ Default ]: due to technical problems I couldn’t unfollow your account from

[ Template ]: unfollow_failure-it
[ Description ]: This text is the «failure» part of the toot that is sent in
reply to an unfollow rquest (italian version).
[ Default ]: a causa di problemi tecnici non sono riuscito ad unfolloware il
tuo account da

[ Template ]: syntax_error-en
[ Description ]: This text is the final part of the toot that is sent in reply
to any malformed command toot (english version).
[ Default ]: I couldn’t understand what you wrote in your toot, if you want to
know which commands I understand please read here: %en_help_url% :-)

[ Template ]: syntax_error-it
[ Description ]: This text is the final part of the toot that is sent in reply
to any malformed command toot (italian version).
[ Default ]: non sono riuscito a capire quel che mi hai scritto nel tuo toot,
se vuoi sapere che comandi capisco per favore leggi qui: %it_help_url% :-)

[ Template ]: wrong_instance_spec-en
[ Description ]: This text is part of any toot that is sent to any (un)follow
request toot with unknown (wrong) instance reference(s) - mind that in some
cases it will be followed by a «: » and a list of such wrong instance
references (english version).
[ Default ]: I couldn’t recognize some of the instance references in your toot

[ Template ]: wrong_instance_spec-it
[ Description ]: This text is part of any toot that is sent to any (un)follow
request toot with unknown (wrong) instance reference(s) - mind that in some
cases it will be followed by a «: » and a list of such wrong instance
references (italian version).
[ Default ]: non riconosco alcuni dei riferimenti a istanze che hai fatto nel
tuo toot
--- End of templates list ---

Idefix currently recognizes and expands the following keywords in templates:

--- Template keywords list ---
%rn%
 Expands to a «new line characters combo» («\r\n»): text will wrap there.

%en_help_url%
 Expands to currently set url for english help (see option «--enhelpurl»).

%it_help_url%
 Expands to currently set url for italian help (see option «--ithelpurl»).

%sender_address%
 Expands to the sender’s full Mastodon address; only available in reply toots,
 not in announcement toots.

%sender_domain%
 Expands to the sender’s instance domain; only available in reply toots, not
 in announcement toots.

%bots_master_address%
 Expands to the currently set «botsmasteraddr» option.

%bots_master_profile_url%
 Expands to the bots master Mastodon profile url according to the currently
 set «botsmasteraddr» option.

%current_bot_address%
 Expands to the addressed bot’s full Mastodon address.

%current_bot_profile_url%
 Expands to the addressed bot’s profile url.

%current_bot_username%
 Expands to the addressed bot’s username.

%current_bot_domain%
 Expands to the addressed bot’s domain.

%current_bot_domain_handle%
 Expands to the addressed bot’s instance’s handle,

%bots_addresses-or%
 Expands to a list of all bots’ full Mastodon addresses separated by «, »,
 with last two separated by « or ».

%bots_addresses-and%
 Expands to a list of all bots’ full Mastodon addresses separated by «, »,
 with last two separated by « and ».

%bots_addresses-o%
 Expands to a list of all bots’ full Mastodon addresses separated by «, »,
 with last two separated by « o ».

%bots_addresses-e%
 Expands to a list of all bots’ full Mastodon addresses separated by «, »,
 with last two separated by « or ».

%bots_addresses_but_current-or%
 Expands to a list of all bots’ full Mastodon addresses, excluding the
 addressed bot’s one, separated by «, », with last two separated by « or ».

%bots_addresses_but_current-and%
 Expands to a list of all bots’ full Mastodon addresses, excluding the
 addressed bot’s one, separated by «, », with last two separated by « and ».

%bots_addresses_but_current-o%
 Expands to a list of all bots’ full Mastodon addresses, excluding the
 addressed bot’s one, separated by «, », with last two separated by « o ».

%bots_addresses_but_current-e%
 Expands to a list of all bots’ full Mastodon addresses, excluding the
 addressed bot’s one, separated by «, », with last two separated by « e ».

%bots_domains-or%
 Expands to a list of all bots’ domains separated by a «, », with last two
 separated by « or ».

%bots_domain-and%
 Expands to a list of all bots’ domains separated by a «, », with last two
 separated by « and ».

%bots_domains-o%
 Expands to a list of all bots’ domains separated by a «, », with last two
 separated by « o ».

%bots_domains-e%
 Expands to a list of all bots’ domains separated by a «, », with last two
 separated by « e ».

%bots_domains_but_current-or%
 Expands to a list of all bots’ domains, excluding the addressed bot’s one,
 separated by a «, », with last two separated by « or ».

%bots_domains_but_current-and%
 Expands to a list of all bots’ domains, excluding the addressed bot’s one,
 separated by a «, », with last two separated by « and ».

%bots_domains_but_current-o%
 Expands to a list of all bots’ domains, excluding the addressed bot’s one,
 separated by a «, », with last two separated by « o ».

%bots_domains_but_current-e%
 Expands to a list of all bots’ domains, excluding the addressed bot’s one,
 separated by a «, », with last two separated by « e ».

%bots_domains_handles-or%
 Expands to a list of all instances handles separated by «, », with last two
 separated by « or ».

%bots_domains_handles-and%
 Expands to a list of all instances handles separated by «, », with last two
 separated by « and ».

%bots_domains_handles-o%
 Expands to a list of all instances handles separated by «, », with last two
 separated by « o » («o» is the italian word for «or»).

%bots_domains_handles-e%
 Expands to a list of all instances handles separated by «, », with last two
 separated by « e » («e» is the italian word for «and»).

%bots_domains_handles_but_current-or%
 Expands to a list of all instances handles, excluding the currently
 considered bot’s one, separated by «, », with last two separated by « or ».

%bots_domains_handles_but_current-and%
 Expands to a list of all instances handles, excluding the currently
 considered bot’s one, separated by «, », with last two separated by « and ».

%bots_domains_handles_but_current_with-o%
 Expands to a list of all instances handles, excluding the currently
 considered bot’s one, separated by «, », with last two separated by « o ».

%bots_domains_handles_but_current_with-e%
 Expands to a list of all instances handles, excluding the currently
 considered bot’s one, separated by «, », with last two separated by « e ».
--- End of template keywords list ---

Let’s make an example of «idefix.templates» template file (template
definitions are kept short in this example, so they don’t wrap in this help
text, but they can have any length).

--- Example «idefix.templates» file ---
# These lines will be ignored, since they are commented out by a «#» at their
# beginning; next line will be ignored too, since it’s empty.

announcement=Hello, I’m %current_bot_address%, an on-demand follow bot.
generic_salutation-en=Hello %sender_address%
follow_failure-en=some technical problems kept me from following you from
generic_salutation-it=Ciao %sender_address%
follow_failure-it=qualche problema tecnico mi ha impedito di seguirti da
--- End of example «idefix.templates» file ---

With this example template file and the example bots config file that you can
read in the «BOTS CONFIG FILE» section above, the announcement toot for the
first defined account would have this content: «Hello, I’m
follbot@amarone.net, an on-demand follow bot.».

[[[  COMMANDS  ]]]

A «command toot» should have this syntax:

<@bot_account> <command>

Idefix understands commands in english and italian language.
«Command» has this syntax:

<«follow me»|«unfollow me»>[ «from» <list of instances|«all[ instances]»>]
 In its simplest forms, «follow me» or «unfollow me», this command will make
 all the bots accounts in the set follow or unfollow the sender’s account; in
 its extended form, «follow me from [instance(s)]» or «unfollow me from
 [instance(s)]», it will make only the bots accounts on the specified
 instances follow or unfollow the sender’s account. The «list of instances»
 can contain both instances’ handles and domains; each one has to be separated
 from the following by at least one space, or by «,» and at least one space.
 If instead of, or inside such a list of instances, an «all» or
 «all instances» string is passed, the sender’s account will be followed
 or unfollowed from all the bot accounts in the set (same as with plain and
 simple «follow me» or «unfollow me»).

<«seguimi|«non seguirmi[ più]»>[ «da» <lista di istanze|«tutte[ le istanze]»>]
 Same as above, in italian language.

--- Example «command toot» ---
@follbot@nebbiolo.org follow me from ostrugo.info, amarone
--- End of example «command toot» ---

With the example bots config file that you can read in the «BOTS CONFIG FILE»
section above, this example «command toot», although addressed to
follbot@nebbiolo.org, would make the sender’s account be followed by
follbot@ostrugo.info and follbot@amarone.net.

Idefix will silently ignore any toot containing the hashtag «#cuccia».

[[[  FILES  ]]]

On every run, idefix writes informations in some files inside the defined
«project directory»; these files are:

«idefix.log»: the log file, storing all info about what idefix does;

«idefix.network»: the «network table» file, storing info about which defined
bot accounts each defined bot account is already following; on first run on
the defined «project directory» and every time idefix finds new bot accounts
definitions in the corresponding «idefix.botsconf» config file (see «BOTS
CONFIG FILE» section above), it makes (only) the necessary «cross-follows» to
ensure each bot account follow each other, and accordingly updates the
«idefix.network» file; you can force a complete «bot accounts network
reconstruction» on next idefix run by simply deleting this file;

«idefix.lastann»: in this file idefix stores the timestamp of the moment the
last «announcement» toot was sent and the address of the bot account it was
sent from (see «--annint» option explanation in the «OPTIONS» section above);

«*.bookmark»: in these files, each named after a defined bot account’s full
Mastodon address, idefix stores the account’s last seen notification id;

«idefix.lock»: this file is created at idefix start and normally deleted on
idefix exit; if this file exists when idefix gets started, idefix assumes
another idefix instance is already running on the «project directory» the lock
file is in, and exits with an error message before doing anything; if you know
for sure that no other idefix is running on that «project directory», you can
force idefix execution by using the «-f» or «--force» option, or by removing
the lock file.

[[[  EXIT VALUES  ]]]

0: regular run
1: initialization error
2: runtime error

[[[  DISCLAIMER AND LICENSE  ]]]

This program comes with ABSOLUTELY NO WARRANTY; for details see the source.
This is free software, and you are welcome to redistribute it under certain
conditions; see <http://www.gnu.org/licenses/> for details.