Skip to content

Commit

Permalink
README updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@Sambigeara
Sambigeara committed Feb 7, 2022
1 parent fed9866 commit 97fad64
Show file tree
Hide file tree
Showing 4 changed files with 46 additions and 209 deletions.
235 changes: 36 additions & 199 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Fuzzynote (fzn)
- [Import/export](#importexport)
- [Future Plans](#future-plans)
- [Issues/Considerations](#issuesconsiderations)
- [Tests](#tests)

[Follow me on Twitter](https://twitter.com/fuzzynote_app) for the latest `fzn` updates and announcements, or just to watch me talk to myself.

Expand Down Expand Up @@ -44,35 +45,16 @@ Zoom in using common prefixes.

Backed by a [CRDT](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type)-based, append-only, mergeable text database.

Collaborate on a list live, or make changes offline and sync later, with guaranteed and consistent output.
Collaboration is done on a per-line/item basis; by adding `@{email}` to the item. Shared lists are displayed by adding the email as a search group.

Rather than collaborating on multiple documents, `fzn` will sync lines matching specific terms to different remotes. Remotes can have any number of "collaborators" with access.
Offline changes will sync later with guaranteed/consistent output.

In short, you can collaborate on multiple "documents" from the same view at the same time.
<br/><br/>

![collaboration](demos/collab.gif)
# S3 ([quickstart](#setup-an-s3-remote))

*Frodo (left) and Joe (right) only share lines with match term `important project`. Non-matched lines remain private. NOTE: Frodo and Joe are using the web support to manage their remotes, and for real time collaboration.*

# Remotes

A "remote" is a remote target where we sync lists.

- Sync all lines, or specify match terms to sync only some. A remote can be a full or partial view.
- Add any number of collaborators who will have access to each remote.

## Web ([quickstart](#web-sign-up-terminal-login))

- Simple remote management
- Real time collaboration
- Managed cloud data store, easy data sync across different computers (simply `fzn login` and start `fzn`)

*Note: for full transparency, if the project takes off, I'll integrate a paid subscription system to enable me to support the infrastructure and the project on an ongoing basis. I'll be proactive in communicating this and will acknowledge any support from early users when making any decisions! Consider this an N-month free trial with "early-release" user status.*

## S3 ([quickstart](#setup-an-s3-remote))

Configure an S3 bucket yourself and share between collaborators for near real-time collaboration and backup.
Configure an S3 bucket yourself to sync between machines/users (accessed via access key/secret)

# Installation

Expand All @@ -83,7 +65,7 @@ Compile locally (requires Go):
```shell
git clone git@github.com:Sambigeara/fuzzynote.git
cd fuzzynote
make build # Installs binary to `/bin/fzn`
make build
```

## Direct download
Expand All @@ -104,9 +86,8 @@ yay -S fuzzynote

- [Basic usage](#basic-usage)
- [Web sign-up, terminal login](#web-sign-up-terminal-login)
- [Add a "remote"](#add-a-remote)
- [Add a collaborator](#add-a-collaborator)
- [Accept an invitation](#accept-an-invitation)
- [Add a friend](#add-a-friend)
- [Share a line with a friend](#share-a-line-with-a-friend)
- [Setup an S3 remote](#setup-an-s3-remote)

## Basic usage
Expand All @@ -120,7 +101,7 @@ yay -S fuzzynote
## Web sign-up, terminal login

1. [Install `fzn`](#installation)
2. Sign up [here](https://fuzzynote.auth.eu-west-1.amazoncognito.com/signup?client_id=5a7brt2fuvlfnl8aql1af3758m&response_type=token&scope=email+openid&redirect_uri=https://github.com/Sambigeara/fuzzynote)
2. Sign up [here](https://fzn.auth.fuzzynote.co.uk/signup?client_id=5a7brt2fuvlfnl8aql1af3758m&redirect_uri=https%3A%2F%2Ffuzzynote.app&response_type=token&scope=profile+email+openid)
3. Login and follow prompts
```shell
./fzn login
Expand All @@ -130,142 +111,24 @@ yay -S fuzzynote
./fzn
```

## Add a "remote"

In this example, Frodo creates a remote for `important project`

1. Open the interactive menu
```shell
./fzn cfg
```
2. Select `Add new remote...`
```shell
# Example output
? Select action:
Remote: main (1748937357)
▸ Add new remote...
Exit
```
3. Specify the name, Frodo chooses `important project`
```shell
✔ Add new remote...
✔ Specify name for new remote: important project
```
4. Select newly created remote
```shell
? Select action:
Remote: main (1748937357)
▸ Remote: important project (8934754397)
Add new remote...
Exit
```
5. Set the "match term"
- **All lines that match this term will sync with the remote**
- **Setting to an empty string will mean that ALL lines will be sync'd and all collaborators will have access**
- **Note**: this includes lines that previously matched the term, but no longer do (e.g. if you delete the particular matching substring from the line)
```shell
# Select "Match"
? Remote: important project (8934754397):
Manage collaborators...
Name: important project
▸ Match: UPDATE ME 2596996162
IsActive: true
Delete? (for all collaborators)
Exit

# Enter new match term and press Enter
✔ Enter new value: important project
```

## Add a collaborator

Joe is invited to the `important project` remote:

```shell
# Select "Manage collaborators..."
? Remote: important project (8934754397):
▸ Manage collaborators...
Name: important project
Match: important project
IsActive: true
Delete? (for all collaborators)
Exit

# Select "Add new collaborator..."
? Manage collaborators:
▸ Add new collaborator...
Exit

# Add email address, and press Enter
✔ Enter email address: joe@bloggs.com
```

## Accept an invitation

Joe responds to the invite above

1. Open the interactive menu

```shell
./fzn cfg
```

2. Select the newly added remote - all invited remotes will start with `INVITE: `

```shell
? Select action:
Remote: main (6782346574)
▸ Remote: INVITE: important project (8934754397)
Add new remote...
Exit
```

3. (Optional) update the name

```shell
# Select "Name"
? Remote: INVITE: important project (8934754397):
▸ Name: INVITE: important project
Match: UPDATE ME 7398574395
IsActive: false
Delete?
Exit

# Enter new name and press Enter
✔ Enter new value: important project
```

4. Update the match term (this can be anything, and does not need to be consistent with other collaborator's match terms - but keeping them consistent is more predictable).

```shell
# Select "Match"
? Remote: important project (8934754397):
Name: important project
▸ Match: UPDATE ME 7398574395
IsActive: false
Delete?
Exit

# Enter new match term and press Enter
✔ Enter new value: important project
```

5. Activate the remote (it's `false` by default to prevent accidental sharing of your personal notes)
## Add a friend

```shell
# Select "IsActive" and choose "true"
? Remote: important project (8934754397):
Name: important project
Match: important project
▸ IsActive: false
Delete?
Exit
1. Sign up/log in
2. Add a line starting with `fzn_cfg:friend `, e.g.
```txt
fzn_cfg:friend {friends_email}
```
3. Ensure you are are connected to the internet
4. Get your friend to do the same (emails swopped, of course)

6. Start the app - the sync will occur in the background and you can start collaborating on the remote
## Share a line with a friend

```shell
./fzn
1. Sign up/log in
2. Add a friend, and have them add you, as per the above
3. In the line you want to share, write the friends email, prefixed with a `@`, e.g.
```txt
fzn_cfg:friend joe@bloggs.com
Some random line I want to share @joe@bloggs.com
```

## Setup an S3 remote
Expand All @@ -283,33 +146,7 @@ s3:
prefix: some_prefix
```

4. **Optional:** specify the "match term" to only sync matching lines:
```yml
s3:
- key: {AWS_ACCESS_KEY}
secret: {AWS_SECRET}
bucket: bucket_name
prefix: some_prefix
match: some match term # Add this to only sync matching lines
```

5. **Optional:** set the `sync` intervals (via envvar or inline flag on startup). The default interval is 10 seconds, meaning `fzn` will flush local changes to the remote every 10 seconds. Likewise, in a separate thread, `fzn` will retrieve new changes _from_ the remote every 10 seconds.

If you want nearer real-time sync (perhaps for collaboration?), you can reduce the interval via an envvar, e.g.:
```shell
export FZN_SYNC_FREQUENCY_MS=1000
```

or in-line:
```shell
./fzn --sync-frequency-ms=1000
```

Each of the above will set to the interval to 1000ms (1 second).

**Note:** extensive I/O to S3 can be more expensive than expected, albeit only pennies in the beginning - worth keeping an eye out if you favour short sync intervals.

5. Start the app, if you haven't already
4. Start the app, if you haven't already
```shell
./fzn
```
Expand All @@ -332,14 +169,14 @@ At present `fzn` only supports S3 as a remote target. However, it is easily exte

Any number of tab-separated search groups are applied to the lists independently. Use full, fuzzy, or inverse string matching.

- Full string match: start the search group with `=`
- Inverse string match (full strings), start the search group with `=!`
- Fuzzy string match, start the search group with `~`
- Inverse string match (full strings), start the search group with `!`
- Separate search groups: `TAB`

```shell
foo # matches "fobo"
=foo # will not match "fobo"
=!foo # will ignore any lines with "foo" in it
~foo # matches "fobo"
foo # will not match "fobo"
!foo # will ignore any lines with "foo" in it
```

## List items (lines)
Expand Down Expand Up @@ -384,11 +221,9 @@ The following character combinations will parse to different useful outputs:
Usage: fzn [options] [arguments]
OPTIONS
--root/$FZN_ROOT <string>
--colour/$FZN_COLOUR <string> (default: light)
--editor/$FZN_EDITOR <string> (default: vim)
--sync-frequency-ms/$FZN_SYNC_FREQUENCY_MS <uint> (default: 10000)
--gather-frequency-ms/$FZN_GATHER_FREQUENCY_MS <uint> (default: 30000)
--root/$FZN_ROOT <string>
--colour/$FZN_COLOUR <string> (default: light)
--editor/$FZN_EDITOR <string> (default: vim)
--help/-h
display this help message
--version/-v
Expand Down Expand Up @@ -418,13 +253,15 @@ Export allows you to generate a plain text file (in the directory from which `fz

# Future plans

- Web-app (Wasm)
- E2E encryption

# Issues/Considerations

The terminal client is fully functioning, however given the early stages of the project, and the (at points) rapid development, there are likely to be some bugs hanging around. Things to look out for:

- If `fzn` is left idle for some time, it might ungracefully error (usually due to some web connection issue) and exit. Under very rare circumstances, it might hang and require the user to kill the process manually (via `kill` commands). Due to the nature of the app, your data will almost certainly be unaffected.
- Sometimes the sync algorithm gets confused. Usually, all that is needed is just to add or delete a line or character (adding additional events to the WAL will trigger a flush and get things moving). If that doesn't work, turning it off and on again usually does the trick.
- Notice something wrong? Please do [open an issue](https://github.com/Sambigeara/fuzzynote/issues/new)!

# Tests

Almost entirely broken. Fuzzynote has undergone some fairly substantial changes over the past few months - the test suite will be updated to suit in due course (please don't judge me).
18 changes: 9 additions & 9 deletions cmd/term/main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,13 +31,13 @@ var (

func main() {
var cfg struct {
Version conf.Version
Root string
Colour string `conf:"default:light"`
Editor string `conf:"default:vim"`
SyncFrequencyMs uint32 `conf:"default:10000"`
GatherFrequencyMs uint32 `conf:"default:30000"`
Args conf.Args
Version conf.Version
Root string
Colour string `conf:"default:light"`
Editor string `conf:"default:vim"`
//SyncFrequencyMs uint32 `conf:"default:10000"`
//GatherFrequencyMs uint32 `conf:"default:30000"`
Args conf.Args
}

// Pre-instantiate default root direct (can't pass value dynamically to default above)
Expand Down Expand Up @@ -143,8 +143,8 @@ func main() {
listRepo := service.NewDBListRepo(
localWalFile,
webTokens,
cfg.SyncFrequencyMs,
cfg.GatherFrequencyMs,
//cfg.SyncFrequencyMs,
//cfg.GatherFrequencyMs,
)

s3Remotes := s3.GetS3Config(cfg.Root)
Expand Down
Binary file removed demos/collab.gif
View file
Binary file not shown.
2 changes: 1 addition & 1 deletion pkg/service/service.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ type DBListRepo struct {
}

// NewDBListRepo returns a pointer to a new instance of DBListRepo
func NewDBListRepo(localWalFile LocalWalFile, webTokenStore WebTokenStore, syncFrequency uint32, gatherFrequency uint32) *DBListRepo {
func NewDBListRepo(localWalFile LocalWalFile, webTokenStore WebTokenStore) *DBListRepo {
listRepo := &DBListRepo{
// TODO rename this cos it's solely for UNDO/REDO
eventLogger: NewDbEventLogger(),
Expand Down

0 comments on commit 97fad64

Please sign in to comment.