bustle/README.md

# bustle

being an ambient activity feed for tilde.town

## development plan

- [ ] skeletal server
- [ ] skeletal client
- [ ] proof of concept inotify handler
- [ ] manually created proof of concept spool files for a few users
- [ ] basic `bustle update <something>`
  - [ ] seeing the update on the server
  - [ ] writing audit log
  - [ ] writing to bustle.log
- [ ] basic `bustle` command
- [ ] bbj integration
- [ ] event aggregation, sampling, and throttling
- [ ] ...honestly if you can even get to here you can worry about what is next then.

## motivation

it's quiet. you've shelled into tilde.town but until you take one of the following actions you will have no idea what else is happening on the server:

- run chat
- run bbj
- run feels

all of these have different problems.

chat:

- it requires energy and social grace
- it might be empty; worse, it might /seem/ empty when you join
- it can get addictive
- it can get heated
- you don't see people that don't like chat. some of those people might be your new best friends.

bbj:

- the pace is slow
- it's hard to tell what conversations are already going
- admin can't figure out how to unsticky stuff

feels:

- the pace is slow
- it's read-only in that you can't respond to people

instead, what about a new command `bustle`:

```
$ bustle

you hear faint noise in the chat room

       ~endorphant is moving around in their home directory

  ~vilmibm just added to their public_html

                     some things are knocking around on bbj

    ~selfsame just created a new file

  there is a rattling sound in ttbp

someone shouts, 'HI WORLD'

                   ~archangelic shouts, 'HELLO BACK'

```

## architecture brainpuke

I am not sure how to do this without a daemon process. Something needs to be listening to inotify
events, listening for shouts, and ready to receive API hooks.

### How should the daemon work?

all updates are written to a ~/.bustle.spool file. bots will need a corresponding user account to
house this file. alternatively, in the future, bustled can be told about bot spool files in a
particular spot; for now there is a one to one between `/home/*/.bustle.spool` files and entities
that can tell bustle about stuff.

these updates are picked up via inotify, which we're already using to aggregate ambient file
activity.

#### (pre-bed thought)

I'm going through the trouble of setting up inotify. For every user. Instead of doing a socket
connection, how about:

- .bustle.spool in each user's directory
- the `bustle` command just writes to it
- i notice those updates by filename and handle them specially

what are the race conditions here? i think it's ok? if it's inotify based...the bustle client
command is just adding to an existing file. the server doesn't care until it's saved and
communicated and will only ever read from it. i think this might work D:


### How should user clients work?

when you run `bustle` with no arguments, it enters a loop. at some interval, messages print. should a connection be
maintained with bustled waiting with recv? I don't think so, since the log is not personalized. what
if `bustle` is just a fancy `tail -f` on a file, `/town/bustle/bustle.log`? i think that's fine. i
want running bustle to be exciting and cute, animating the messages in various ways. someone who
just wants the log is free to read `/town/bustle/bustle.log`.


### How should API clients work?

I'd like to be able to report on irc, bbj, and feels events. feels can be a special case of just
users editing in their home dir, but bbj and irc are more special. i think to start those services
will just get a spool file like a normal user and then write to it programmatically. this will
require modification of bbj and hooking into an irc bot run as some user.