In the previous step you added profiles and rooms. Now one app keeps several conversations: a "Family" and a "Work" in the same window, each with its own members, rooms and messages.
The chat code you wrote in steps 2 to 5 does not change much. It becomes the engine of one conversation, and a new service, Conversations, runs one engine per conversation and routes every call of the window to the right one. Each conversation lives in a folder of its own, with its own key, kolo-id, logs, pin capability and invites.
This step is backend only, as step 5 was: you write the Go code below in the project of the previous step. The window of this step, with its list of conversations, is already built, and you bring it in with one command.
1Check what you need
You need what step 5 needed: Go 1.26 or newer, Node.js, wails3, the bootstrap node and a local pin. Start from the project you finished in step 5. This step adds no library.
2Bring the window
The window of this step has a new first column, the full height of the window, with your conversations, the count of new messages in each, "New conversation" and "Join with an invite". Every call it makes names the conversation it is about. It is already built: bring it from the tag step-6. The tag also holds the finished version of every file below, in case you want to compare yours with it.
git fetch origin --tagsgit checkout step-6 -- frontend3Keep each conversation in its own folder
Until now one data folder was one conversation: its key, its kolo-id, its logs and its invites sat at the top of the folder. Now the top of the folder holds a layout.json that says how the folder is organised, and a conversations/ folder with one folder per conversation:
<data>/ 0700
layout.json {"layout":2}, written once in a new data folder
conversations/ 0700
<id>/ 0700; 32 hex characters from crypto/rand, not from the key
identity.key the kolo-id of this conversation
local.json the name only you see, and when it was added
conversation.json the key and the pin (not there while a join waits)
members.json, directory-log, store/, invites/, pin-token as in step 5The ID of a conversation's folder is random, so it says nothing about the key. Its name is local: it lives in local.json, it is never sent, and only you see it.
A data folder of step 5 has no layout.json and holds the files of its one conversation at its top. The app refuses it and changes nothing in it: there is no migration, and nothing is moved or deleted. The message names the folder, so you can move it aside and start again. A layout.json of another layout, or a damaged one, is refused the same way, and so is a data folder that other users can open, since they could rename or replace what the app keeps there. Before this step the kolo-id file at the top of the folder made kolo-id refuse such a folder; now the app checks it itself.
Create conversations.go with:
package main
//lint:file-ignore ST1005 these errors are sentences the window shows as they are
// Several conversations in one app.
//
// Each conversation lives in a folder of its own, <data>/conversations/<id>, with its own engine (ChatService) and
// so its own kolo-id, swarm, logs, pin and invites. One engine per conversation follows the rules of the libraries
// as they are: a pin keeps the newest capability of each owner, and a connection to a peer key serves one protocol.
// Conversations lists the folders, starts an engine for each, and routes every call of the window by ID.
import (
"cmp"
"crypto/rand"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io/fs"
"log"
"os"
"path/filepath"
"runtime"
"slices"
"strings"
"sync"
"time"
"unicode/utf8"
)Add to conversations.go the bounds, the names a folder of step 5 holds, and the errors. Each error is a sentence the window shows as it is:
const (
layoutVersion = 2
layoutFile = "layout.json"
conversationDir = "conversations"
localFile = "local.json"
defaultConvName = "Conversation"
maxConvName = 32 // characters in a conversation's name, as in a room's
maxConversations = 8 // engines one app runs, each with its own socket, swarm and two stores
)
// oldLayoutNames are the files a data folder of step 5 or older held at its top, for its one conversation.
var oldLayoutNames = []string{"identity.key", "conversation.json", "members.json", "directory-log", "store", "invites", "pin-token"}
var (
// ErrOldLayout matches the *DataDirError of a data folder of step 5 or older (Layout 1).
ErrOldLayout = errors.New("data folder made by Kolo Chat step 5 or older")
ErrUnknownConversation = errors.New("That conversation is not on this computer.")
ErrTooManyConversations = errors.New("You have the most conversations this app keeps.")
ErrNoPins = errors.New("Start Kolo Chat with -pin-key to start a conversation. You can still join one with an invite.")
ErrInvalidName = errors.New("That name cannot be used")
errNotStarted = errors.New("not started")
)The refusal is a typed error that names the folder, so the window can show it and the code can ask errors.Is(err, ErrOldLayout):
// DataDirError is returned for a data folder this version cannot use, and nothing in it is changed. Layout 1 is a
// folder of step 5 or older, which held one conversation; another Layout is one of another version (-1: its
// layout.json is damaged), and Open one that other users can open. Dir is that folder.
type DataDirError struct {
Dir string `json:"dir"`
Layout int `json:"layout,omitempty"`
Open bool `json:"open,omitempty"`
}
func (e *DataDirError) Error() string {
switch {
case e.Open:
return "The data folder " + e.Dir + " is open to other users, who could change what Kolo Chat keeps in it. " +
"Run chmod 700 on it, or start with another -data. Nothing in the folder is changed."
case e.Layout == 1:
return "The data folder " + e.Dir + " holds one conversation of Kolo Chat step 5 or older, and this version keeps " +
"each conversation in a folder of its own. Quit Kolo Chat, move or rename that folder (nothing in it is " +
"deleted), then open Kolo Chat again: start a new conversation, or paste a new invite."
}
return fmt.Sprintf("The data folder %s was made by another version of Kolo Chat (layout %d). Use that version, "+
"or start with another -data. Nothing in the folder is changed.", e.Dir, e.Layout)
}
func (e *DataDirError) Is(target error) bool { return e.Layout == 1 && target == ErrOldLayout }openLayout runs first at every start. It writes layout.json only in a new folder, after it has checked that none of the names of step 5 is there:
// localInfo is local.json: the name only we see, and when the conversation was added here, in Unix seconds.
type localInfo struct {
Name string `json:"name"`
Created int64 `json:"created"`
}
// openLayout checks the data folder's layout.json, or writes it in a new folder. A folder of step 5 or older, or of
// another layout, is refused and nothing in it is changed: there is no migration.
func openLayout(root string) error {
if err := os.MkdirAll(root, 0o700); err != nil {
return err
}
if err := privateDir(root); err != nil {
return err
}
data, err := os.ReadFile(filepath.Join(root, layoutFile))
switch {
case err == nil:
var l struct {
Layout int `json:"layout"`
}
if json.Unmarshal(data, &l) != nil || l.Layout < layoutVersion {
return &DataDirError{Dir: root, Layout: -1}
}
if l.Layout != layoutVersion {
return &DataDirError{Dir: root, Layout: l.Layout}
}
if err := os.MkdirAll(filepath.Join(root, conversationDir), 0o700); err != nil { // deleted by hand: start empty
return err
}
return privateDir(filepath.Join(root, conversationDir))
case !errors.Is(err, fs.ErrNotExist): // a folder or a file we cannot read: no version wrote it
return &DataDirError{Dir: root, Layout: -1}
}
for _, name := range oldLayoutNames {
if _, err := os.Lstat(filepath.Join(root, name)); !errors.Is(err, fs.ErrNotExist) {
return &DataDirError{Dir: root, Layout: 1}
}
}
if err := os.MkdirAll(filepath.Join(root, conversationDir), 0o700); err != nil {
return err
}
if err := privateDir(filepath.Join(root, conversationDir)); err != nil {
return err
}
return writeJSON(filepath.Join(root, layoutFile), map[string]int{"layout": layoutVersion})
}
// privateDir refuses a folder that other users can open, who could list, rename or replace what the app keeps
// there. Windows has no such mode bits; there the folder's place in the user's profile protects it.
func privateDir(dir string) error {
fi, err := os.Stat(dir)
if err != nil {
return err
}
if runtime.GOOS != "windows" && fi.Mode().Perm()&0o077 != 0 {
return &DataDirError{Dir: dir, Open: true}
}
return nil
}The list of conversations is the listing of conversations/, so there is no second list to keep in step with it. A folder without a conversation.json is a join that waits for an invite's answer. A missing or damaged local.json gives the name "Conversation", and the conversation still opens:
// listConversations lists the conversation folders, oldest first. Of the folders without a conversation.json, the
// joins that wait, only the first is used.
func listConversations(root string) ([]*convEntry, error) {
dir := filepath.Join(root, conversationDir)
items, err := os.ReadDir(dir)
if err != nil {
return nil, err
}
var all []*convEntry
for _, it := range items {
if !it.IsDir() || !validID(it.Name()) {
log.Printf("%s/%q: not a conversation, ignored", conversationDir, it.Name())
continue
}
e := &convEntry{id: it.Name(), dir: filepath.Join(dir, it.Name())}
e.local = loadLocal(e.dir)
_, err := os.Lstat(filepath.Join(e.dir, "conversation.json"))
e.joined = err == nil
all = append(all, e)
}
slices.SortFunc(all, compareEntries)
out, pending := all[:0], false
for _, e := range all {
if !e.joined && pending {
log.Printf("%s/%s: not a conversation, ignored", conversationDir, e.id)
continue
}
pending = pending || !e.joined
out = append(out, e)
}
return out, nil
}
func compareEntries(x, y *convEntry) int {
return cmp.Or(cmp.Compare(x.local.Created, y.local.Created), strings.Compare(x.id, y.id))
}
// loadLocal reads local.json. A damaged or missing one gives the name "Conversation", and the conversation opens.
func loadLocal(dir string) localInfo {
var l localInfo
data, err := os.ReadFile(filepath.Join(dir, localFile))
if err == nil {
err = json.Unmarshal(data, &l)
}
if err != nil {
return localInfo{Name: defaultConvName}
}
if l.Name, err = convName(l.Name, defaultConvName); err != nil {
l.Name = defaultConvName
}
return l
}
// convName checks a conversation's name: plain text of 1 to maxConvName characters. An empty one is def, or refused
// when def is empty.
func convName(name, def string) (string, error) {
if name = strings.TrimSpace(name); name == "" {
name = def
}
if name == "" || utf8.RuneCountInString(name) > maxConvName || !plainText(name) {
return "", fmt.Errorf("%w: a name has 1 to %d characters, with no control characters.", ErrInvalidName, maxConvName)
}
return name, nil
}
// validID says whether id is one the app makes: 32 lowercase hex characters.
func validID(id string) bool {
return len(id) == 32 && strings.Trim(id, "0123456789abcdef") == ""
}
// writeJSON replaces the file at path with v in one step, mode 0600.
func writeJSON(path string, v any) error {
data, err := json.Marshal(v)
if err != nil {
return err
}
tmp := path + ".tmp"
if err := os.WriteFile(tmp, data, 0o600); err != nil {
return err
}
return os.Rename(tmp, path)
}4Give each conversation its own kolo-id and swarm
Why not one kolo-id and one swarm for all the conversations? Two rules of the libraries decide it. A pin keeps the newest capability of each owner, so with one kolo-id the capability of one conversation would take the logs of the other off the pin. And one connection to a peer key serves one protocol, so someone already connected to you in one conversation could not run another conversation's invite on that connection. With one engine per conversation neither can happen, and the code of steps 2 to 5 stays as it is.
The window gets a list of ConversationInfo, and every event of an engine reaches it as a ConvEvent, with the ID of its conversation:
// ConversationInfo is one conversation as the window lists it. Me is our kolo-id in it, Joined is false for the
// join that waits for an invite's answer, and Error says why it did not start, with the Folder it is in.
type ConversationInfo struct {
ID string `json:"id"`
Name string `json:"name"`
Me string `json:"me"`
Joined bool `json:"joined"`
Owner bool `json:"owner"`
Error string `json:"error"`
Folder string `json:"folder"`
}
// AppInfo is what Start returns. CanCreate says the app has a pin, which a new conversation needs.
type AppInfo struct {
Conversations []ConversationInfo `json:"conversations"`
MaxConversations int `json:"maxConversations"`
CanCreate bool `json:"canCreate"`
}
// ConvEvent is the payload of every chat event: the conversation it is about, and the engine's payload.
type ConvEvent struct {
Conv string `json:"conv"`
Data any `json:"data"`
}
// convEntry is one conversation folder and its engine, nil when it did not start.
type convEntry struct {
id, dir string
local localInfo
joined bool
chat *ChatService
me string
err error
}
// Conversations is the window's service: it keeps one engine per conversation folder and routes every call by ID.
type Conversations struct {
cfg Config
emit func(name string, data any)
opMu sync.Mutex // one Start, Create, Join or ServiceShutdown at a time
set settings
root string
mu sync.Mutex // guards the fields below
started bool
convs map[string]*convEntry
}
// NewConversations returns the service that reads cfg when it starts and tells the window what happens through emit.
func NewConversations(cfg Config, emit func(name string, data any)) *Conversations {
return &Conversations{cfg: cfg, emit: emit}
}An engine is a ChatService with the app's configuration, in the conversation's folder. The key, the pin and the token of the command line go only to the conversation they name. The emit of the engine wraps every event with the ID:
// engineConfig is the configuration of one engine: the app's, in the conversation's folder. The key, the pin and
// the token are only for the -conversation-key conversation; every other one reads its own conversation.json.
func (a *Conversations) engineConfig(dir string, configured bool) Config {
cfg := a.cfg
cfg.DataDir = dir
if !configured {
cfg.ConversationKey, cfg.PinAddr, cfg.PinKey, cfg.PinToken = "", "", "", ""
}
return cfg
}
// startEngine starts the conversation's engine, whose events go to the window tagged with the conversation's ID.
func (a *Conversations) startEngine(e *convEntry, cfg Config) {
c := NewChatService(cfg, func(name string, data any) { a.emit(name, ConvEvent{Conv: e.id, Data: data}) })
if e.me, e.err = c.Start(); e.err == nil {
e.chat, e.joined = c, c.Joined()
} else {
log.Printf("conversation %s did not start: %v", e.id, e.err)
}
}
func (a *Conversations) add(e *convEntry) {
a.mu.Lock()
defer a.mu.Unlock()
a.convs[e.id] = e
}5Start and join conversations
Start opens the data folder, lists the conversations and starts every engine at once. A conversation that does not start shows why in its row of the list, with its folder, and the others run. -conversation-key still works: it starts the folder whose conversation.json holds that key, or makes one for it. A fixed -listen port can hold one conversation only, since every engine has its own socket:
// Start opens the data folder and starts every conversation in it, each on its own. It fails only for a bad
// setting (*ConfigError) or a data folder it cannot use (*DataDirError): a conversation that does not start
// shows its Error in the list, and the others run.
func (a *Conversations) Start() (AppInfo, error) {
a.opMu.Lock()
defer a.opMu.Unlock()
if a.isStarted() {
return a.info(), nil
}
set, err := a.cfg.resolve()
if err != nil {
return AppInfo{}, err
}
if err := openLayout(set.DataDir); err != nil {
return AppInfo{}, err
}
entries, err := listConversations(set.DataDir)
if err != nil {
return AppInfo{}, err
}
a.set, a.root = set, set.DataDir
configured, err := a.findConfigured(entries)
if err != nil {
return AppInfo{}, err
}
isNew := configured != nil && !slices.Contains(entries, configured)
if isNew {
entries = append(entries, configured)
}
if set.fixedPort() && len(entries) > 1 {
if isNew {
a.dropFolder(configured)
}
return AppInfo{}, &ConfigError{Setting: "listen", Err: errFixedPort}
}
a.mu.Lock()
a.started, a.convs = true, map[string]*convEntry{}
a.mu.Unlock()
var wg sync.WaitGroup
for _, e := range entries {
wg.Go(func() { a.startEngine(e, a.engineConfig(e.dir, e == configured)) })
}
wg.Wait()
for _, e := range entries {
a.add(e)
}
if isNew && configured.err != nil { // a bad setting, such as a -pin-token, as before there were several
a.dropFolder(configured)
a.shutdown()
return AppInfo{}, configured.err
}
a.emitList()
return a.info(), nil
}
// findConfigured returns the conversation that -conversation-key names: the folder whose conversation.json holds
// the key, or a new folder for it. It is nil without the setting.
func (a *Conversations) findConfigured(entries []*convEntry) (*convEntry, error) {
if !a.set.inConversation {
return nil, nil
}
for _, e := range entries {
if v, found, err := loadConversation(e.dir); err == nil && found && slices.Equal(v.Key, a.set.conversationKey[:]) {
return e, nil
}
}
return a.newFolder(defaultConvName)
}Create starts a conversation that you own. Its key is 32 bytes from crypto/rand, held in memory until the engine saves it in conversation.json, mode 0600. It uses the pin of -pin and -pin-key. A Create that fails before the key is saved removes its new folder:
// Create starts a new conversation that we own, with a key from crypto/rand and the app's pin. name is only ours.
func (a *Conversations) Create(name string) (ConversationInfo, error) {
a.opMu.Lock()
defer a.opMu.Unlock()
name, err := convName(name, defaultConvName)
if err != nil {
return ConversationInfo{}, err
}
if err := a.hasRoom(); err != nil {
return ConversationInfo{}, err
}
if len(a.set.pinKey) == 0 {
return ConversationInfo{}, ErrNoPins
}
e, err := a.newFolder(name)
if err != nil {
return ConversationInfo{}, err
}
key := make([]byte, 32)
if _, err := rand.Read(key); err != nil {
a.dropFolder(e)
return ConversationInfo{}, err
}
cfg := a.engineConfig(e.dir, false)
cfg.ConversationKey, cfg.PinAddr, cfg.PinKey = hex.EncodeToString(key), a.cfg.PinAddr, a.cfg.PinKey
clear(key)
if a.startEngine(e, cfg); e.err != nil {
a.dropFolder(e)
return ConversationInfo{}, e.err
}
a.add(e)
a.emitList()
return a.infoOf(e), nil
}
// newFolder makes the folder of a new conversation, with a random ID that has nothing to do with its key.
func (a *Conversations) newFolder(name string) (*convEntry, error) {
b := make([]byte, 16)
if _, err := rand.Read(b); err != nil {
return nil, err
}
id := hex.EncodeToString(b)
e := &convEntry{id: id, dir: filepath.Join(a.root, conversationDir, id), local: localInfo{Name: name, Created: time.Now().Unix()}}
if err := os.Mkdir(e.dir, 0o700); err != nil {
return nil, err
}
if err := writeJSON(filepath.Join(e.dir, localFile), e.local); err != nil {
os.RemoveAll(e.dir)
return nil, err
}
return e, nil
}
// dropFolder removes the folder of a conversation that failed before it had a conversation.json: nothing in it is
// worth keeping.
func (a *Conversations) dropFolder(e *convEntry) {
if _, err := os.Lstat(filepath.Join(e.dir, "conversation.json")); errors.Is(err, fs.ErrNotExist) {
os.RemoveAll(e.dir)
}
}Join takes an invite code and a name. Each invite is a conversation of its own, in a new folder with a new kolo-id, so the person who invited you is never already connected to that kolo-id. A Join that fails, or that you cancel, keeps its folder, and the next Join takes it again. The bound of eight conversations counts the join that waits:
// Join uses an invite code in the join that waits, or in a new folder: each invite is a conversation of its own,
// with a new kolo-id. A Join that fails or is cancelled keeps that folder for the next one.
func (a *Conversations) Join(code, name string) (ConversationInfo, error) {
name, err := convName(name, defaultConvName)
if err != nil {
return ConversationInfo{}, err
}
a.opMu.Lock()
e, err := a.pendingJoin()
a.opMu.Unlock()
if err != nil {
return ConversationInfo{}, err
}
if err := e.chat.Join(code); err != nil {
return ConversationInfo{}, err
}
a.opMu.Lock()
defer a.opMu.Unlock()
a.mu.Lock()
e.local.Name, e.joined = name, true
local := e.local
a.mu.Unlock()
if err := writeJSON(filepath.Join(e.dir, localFile), local); err != nil {
log.Print("conversation name: ", err) // the conversation works, and shows as "Conversation" after a restart
}
a.emitList()
return a.infoOf(e), nil
}
// pendingJoin returns the conversation that waits for a join, made and started when there is none. One that did not
// start is refused with its error: its folder has to be moved first.
func (a *Conversations) pendingJoin() (*convEntry, error) {
a.mu.Lock()
var pending *convEntry
for _, e := range a.convs {
if !e.joined {
pending = e
}
}
a.mu.Unlock()
switch {
case pending != nil && pending.chat == nil:
return nil, pending.err
case pending != nil:
return pending, nil
}
if err := a.hasRoom(); err != nil {
return nil, err
}
e, err := a.newFolder(defaultConvName)
if err != nil {
return nil, err
}
if a.startEngine(e, a.engineConfig(e.dir, false)); e.err != nil {
a.dropFolder(e)
return nil, e.err
}
a.add(e)
a.emitList() // the window shows the kolo-id the join uses, for an invite that needs approval
return e, nil
}
// CancelJoin stops the Join that waits, for the inviter or for its answer.
func (a *Conversations) CancelJoin() {
a.mu.Lock()
var c *ChatService
for _, e := range a.convs {
if !e.joined && e.chat != nil {
c = e.chat
}
}
a.mu.Unlock()
if c != nil {
c.CancelJoin()
}
}
// hasRoom says whether one more conversation may be added: the bound counts the join that waits and the ones that
// did not start, and a fixed -listen port holds one conversation only.
func (a *Conversations) hasRoom() error {
a.mu.Lock()
defer a.mu.Unlock()
switch n := len(a.convs); {
case !a.started:
return errNotStarted
case n >= maxConversations:
return ErrTooManyConversations
case n >= 1 && a.set.fixedPort():
return &ConfigError{Setting: "listen", Err: errFixedPort}
}
return nil
}6Route the window's calls to the right conversation
Every call of the window names its conversation. engine looks the ID up in the map of running engines and returns ErrUnknownConversation for any other. The map holds only IDs that the app listed or made, so no path is ever built from what the window sends:
// List returns the conversations in the order they were added, never nil.
func (a *Conversations) List() []ConversationInfo {
a.mu.Lock()
entries := make([]convEntry, 0, len(a.convs))
for _, e := range a.convs {
entries = append(entries, *e)
}
a.mu.Unlock()
slices.SortFunc(entries, func(x, y convEntry) int { return compareEntries(&x, &y) })
out := make([]ConversationInfo, 0, len(entries))
for _, e := range entries {
out = append(out, e.info())
}
return out
}
func (e convEntry) info() ConversationInfo {
info := ConversationInfo{ID: e.id, Name: e.local.Name, Me: e.me, Joined: e.joined}
if e.chat != nil {
info.Owner = e.chat.IsOwner()
}
if e.err != nil {
info.Error, info.Folder = e.err.Error(), e.dir
}
return info
}
func (a *Conversations) info() AppInfo {
return AppInfo{Conversations: a.List(), MaxConversations: maxConversations, CanCreate: len(a.set.pinKey) > 0}
}
func (a *Conversations) infoOf(e *convEntry) ConversationInfo {
a.mu.Lock()
snapshot := *e
a.mu.Unlock()
return snapshot.info()
}
func (a *Conversations) emitList() { a.emit("chat:conversations", a.List()) }// Send, Members and the methods down to Deny are the engine's, for the conversation conv.
func (a *Conversations) Send(conv, room, text string) error {
return call(a, conv, func(c *ChatService) error { return c.Send(room, text) })
}
func (a *Conversations) Members(conv string) ([]Member, error) {
return get(a, conv, (*ChatService).Members)
}
func (a *Conversations) Rooms(conv string) ([]string, error) {
return get(a, conv, (*ChatService).Rooms)
}
func (a *Conversations) IsOwner(conv string) (bool, error) {
return get(a, conv, (*ChatService).IsOwner)
}
func (a *Conversations) SetProfile(conv, name, avatar string) error {
return call(a, conv, func(c *ChatService) error { return c.SetProfile(name, avatar) })
}
func (a *Conversations) AddRoom(conv, name string) error {
return call(a, conv, func(c *ChatService) error { return c.AddRoom(name) })
}
func (a *Conversations) CreateInvite(conv string, opts InviteOptions) (InviteInfo, error) {
c, err := a.engine(conv)
if err != nil {
return InviteInfo{}, err
}
return c.CreateInvite(opts)
}
func (a *Conversations) Invites(conv string) ([]InviteInfo, error) {
c, err := a.engine(conv)
if err != nil {
return nil, err
}
return c.Invites()
}
func (a *Conversations) Revoke(conv, id string) error {
return call(a, conv, func(c *ChatService) error { return c.Revoke(id) })
}
func (a *Conversations) Approve(conv string, request uint64) error {
return call(a, conv, func(c *ChatService) error { return c.Approve(request) })
}
func (a *Conversations) Deny(conv string, request uint64) error {
return call(a, conv, func(c *ChatService) error { return c.Deny(request) })
}// engine returns the running engine of conv. Only IDs the app listed or made are in the map, so no path is ever
// built from what the window sends.
func (a *Conversations) engine(conv string) (*ChatService, error) {
a.mu.Lock()
defer a.mu.Unlock()
if e := a.convs[conv]; e != nil && e.chat != nil {
return e.chat, nil
}
return nil, ErrUnknownConversation
}
func call(a *Conversations, conv string, f func(*ChatService) error) error {
c, err := a.engine(conv)
if err != nil {
return err
}
return f(c)
}
func get[T any](a *Conversations, conv string, f func(*ChatService) T) (T, error) {
c, err := a.engine(conv)
if err != nil {
var zero T
return zero, err
}
return f(c), nil
}When the app quits, Wails calls ServiceShutdown, which stops every engine:
// ServiceShutdown stops every conversation. Wails calls it when the app quits.
func (a *Conversations) ServiceShutdown() error {
a.opMu.Lock()
defer a.opMu.Unlock()
return a.shutdown()
}
func (a *Conversations) shutdown() error {
a.mu.Lock()
engines := a.running()
a.started, a.convs = false, nil
a.mu.Unlock()
errs := make([]error, len(engines))
var wg sync.WaitGroup
for i, c := range engines {
wg.Go(func() { errs[i] = c.ServiceShutdown() })
}
wg.Wait()
return errors.Join(errs...)
}
// running returns the engines that run. The caller holds mu.
func (a *Conversations) running() []*ChatService {
var out []*ChatService
for _, e := range a.convs {
if e.chat != nil {
out = append(out, e.chat)
}
}
return out
}
func (a *Conversations) isStarted() bool {
a.mu.Lock()
defer a.mu.Unlock()
return a.started
}7Let the pin start conversations
In step 5, -pin-key was refused without -conversation-key. Now -pin and -pin-key name the pin of the conversations you start in the window, so -pin-key is accepted alone. -pin-token still needs -conversation-key: a token is issued by one kolo-id, and only that conversation has it.
In config.go, replace the causes of a ConfigError with:
// Causes of a ConfigError, besides the errors of kolo-pin for a bad token.
var (
ErrMissing = errors.New("is required")
ErrMalformed = errors.New("is malformed")
errFixedPort = errors.New("has a fixed port, which only one conversation can use: use port 0")
)In config.go, replace Config with:
// Config is everything the chat needs from outside. A zero field takes its default, if it has one.
// LoadConfig fills it from flags and environment variables.
type Config struct {
DataDir string // -data, KOLO_CHAT_DATA: one folder per conversation, see conversations.go. Default: <user config dir>/kolo-chat
Bootstrap string // -bootstrap, KOLO_CHAT_BOOTSTRAP: IP:PORT of a bootstrap node. Default 127.0.0.1:4000
Listen string // -listen, KOLO_CHAT_LISTEN: local IP:PORT of every conversation. Default 127.0.0.1:0; a fixed port allows one conversation
ConversationKey string // -conversation-key, KOLO_CHAT_CONVERSATION_KEY: 64 hex characters (32 bytes), the key of one conversation, kept in its folder. Empty to start conversations in the window or join with an invite
PinAddr string // -pin, KOLO_CHAT_PIN: IP:PORT of the pin. Default 127.0.0.1:7450. The pin of the conversations started here; a joiner gets the pin from the invite
PinKey string // -pin-key, KOLO_CHAT_PIN_KEY: the pin's public key in hex (`kolo-pin id`). Required with a conversation key and to start conversations in the window
PinToken string // -pin-token, KOLO_CHAT_PIN_TOKEN: a capability in hex for the -conversation-key conversation, issued by its kolo-id. Default: the app issues one
PinTTL time.Duration // -pin-ttl, KOLO_CHAT_PIN_TTL: lifetime of the capability the app issues. Default 720h
PinQuota uint64 // -pin-quota, KOLO_CHAT_PIN_QUOTA: bytes the pin may keep for you, in the capability the app issues. Default 16777216
LookupInterval time.Duration // -lookup-interval, KOLO_CHAT_LOOKUP_INTERVAL: time between topic lookups. Default 5s
}In LoadConfig, replace the lines of conversation-key, pin, pin-key and pin-token with:
{"conversation-key", "KOLO_CHAT_CONVERSATION_KEY", "32-byte key of one conversation, in hex (leave it out to start conversations in the window or join with an invite)", text(&c.ConversationKey)},
{"pin", "KOLO_CHAT_PIN", "IP:PORT of the pin (default " + defaultPinAddr + ")", text(&c.PinAddr)},
{"pin-key", "KOLO_CHAT_PIN_KEY", "public key of the pin, in hex: the pin of the conversations you start (required with -conversation-key)", text(&c.PinKey)},
{"pin-token", "KOLO_CHAT_PIN_TOKEN", "capability for the pin of the -conversation-key conversation, in hex (default: issued by the app)", text(&c.PinToken)},In config.go, replace the comment of resolve with:
// resolve applies the defaults and checks every setting, returning a *ConfigError for the first bad one.
// Without a conversation key a chat starts as a joiner: the key and the pin come from an invite (see
// useConversation). The pin is then the one of the conversations started in the window, and a token, which is
// for the key's conversation only, is refused. A token is checked later, in capability, because it needs the
// identity.
func (c Config) resolve() (settings, error) {In resolve, replace the checks of the conversation key and the pin key, down to s.inConversation = true, with:
if c.ConversationKey == "" && c.PinToken != "" {
return s, &ConfigError{Setting: "conversation-key", Err: ErrMissing}
}
if c.ConversationKey != "" || c.PinKey != "" {
s.pinKey = make(ed25519.PublicKey, ed25519.PublicKeySize)
if err := parseHex("pin-key", c.PinKey, s.pinKey); err != nil {
return s, err
}
}
if c.ConversationKey == "" {
return s, nil
}
if err := parseHex("conversation-key", c.ConversationKey, s.conversationKey[:]); err != nil {
return s, err
}
s.inConversation = trueAdd to config.go:
// fixedPort says whether the listen address names a port, which one socket only can hold.
func (s settings) fixedPort() bool {
ap, err := netip.ParseAddrPort(s.Listen)
return err == nil && ap.Port() != 0
}An owner of step 5 gave its key on every start. A conversation made with New conversation has its key only in its folder, so the engine now keeps the key it was given in conversation.json. In invite.go, replace savedConversation with:
// savedConversation returns the conversation this chat is in at start: the one in the configuration, or the one
// the data directory keeps, from an invite or from an earlier start with a key. A joiner that has none yet returns
// false. The configured one is kept, so the app finds it again after a restart.
func (c *ChatService) savedConversation() (conversation, bool, error) {
saved, found, err := loadConversation(c.set.DataDir)
if err != nil {
return saved, false, err
}
if !c.set.inConversation {
return saved, found, nil
}
mine := conversation{Key: slices.Clone(c.set.conversationKey[:]), PinAddr: c.set.PinAddr, PinKey: slices.Clone(c.set.pinKey), Owner: slices.Clone(c.pub)}
if found && !slices.Equal(saved.Key, mine.Key) {
err := errors.New("is not the conversation this data directory joined with an invite: use another -data")
return mine, false, &ConfigError{Setting: "conversation-key", Err: err}
}
if found {
mine.Owner = saved.Owner // a member that also has the key is still a member
}
if err := saveConversation(c.set.DataDir, mine); err != nil {
return mine, false, err
}
return mine, true, nil
}The engine is no longer the window's service. In chatservice.go, add this comment above ChatService:
// ChatService is the engine of one conversation: its own kolo-id, swarm, logs, pin and invites in its own folder.
// Conversations runs one per conversation and routes the window's calls to it.
type ChatService struct {In chatservice.go, replace the comment of ServiceShutdown with:
// ServiceShutdown stops the chat and closes the store. Conversations calls it when the app quits.
func (c *ChatService) ServiceShutdown() error {8Wire it into main.go
The window now talks to Conversations. In main.go, replace the comment above emit and the service with:
// Each conversation tells the window what happens by emitting events; the Wails app is only needed once one is.
emit := func(name string, data any) { application.Get().Event.Emit(name, data) }
app := application.New(application.Options{
Name: "Kolo Chat",
Description: "Peer-to-peer desktop chat built with Kolo",
Icon: appIcon,
Services: []application.Service{
application.NewService(NewConversations(cfg, emit)),9What the window does with it
The window keeps the state of each conversation apart. It listens to every chat event and gives it to the conversation it names, and to the list:
const offs = CHAT_EVENTS.map((name) => Events.On(name, (e) => dispatch({ type: 'event', name, payload: e.data })))
offs.push(Events.On('chat:conversations', (e) => dispatch({ type: 'list', list: e.data })))Sending names the selected conversation:
Send(id, room, text)
.then(() => {
setError('')
dispatch({ type: 'sent', conv: id, from: row.me, room, text })
})
.catch((err) => setError(errorText(err)))New conversation calls Create with the name you typed:
Create(name)
.then((info) => {
setName('')
setNaming(false)
onCreated(info)
})
.catch((err) => setError(errorText(err)))And Join with an invite calls Join with the code and the name:
Join(code, name)
.then((info) => onJoined(info))10Run it
Start the bootstrap node, and keep it running:
go run ./cmd/bootstrapIn another terminal, start the local pin, and keep it running:
go run github.com/ciranda-dev/kolo-pin/cmd/kolo-pin run -data .data/pin -max-bytes 100MBBuild the app:
GOWORK=off wails3 buildThe data folders of step 5 are refused now. Try it, if you like: the window names the folder and says that nothing in it was changed.
./bin/kolo-chat -data .data/aliceSo use new folders. Alice needs only the pin's public key, in her terminal only, to start conversations:
export KOLO_CHAT_PIN_KEY=$(go run github.com/ciranda-dev/kolo-pin/cmd/kolo-pin id -data .data/pin)./bin/kolo-chat -data .data/alice-6In Alice's window click New conversation, type "Family" and click Create. Do it again with "Work". Each conversation has its own kolo-id: the start of the key next to "you" changes when you select the other one.
Start Bob in another terminal, without the variable:
./bin/kolo-chat -data .data/bob-6Bob joins both. In Alice's window select Family, click Invite and create an invite. In Bob's window click Join with an invite, paste the code, type the name "Family" and click Join. With "Require my approval", Alice sees "wants to join" under Family and clicks Approve. Then do the same with Work. Bob joins Alice's second conversation while he is in her first: for him, Alice's other kolo-id is a stranger.
Start Carol in a third terminal, and invite her to Work only:
./bin/kolo-chat -data .data/carol-6Send a message in Family and one in Work. Each one shows in its own conversation only. Carol's window has Work and nothing of Family. When a message comes in a conversation you have not selected, the list shows how many are new.
11Run the tests
The tag has the tests of this step: two conversations that never see each other's messages, a second join while you are in the first, both conversations on one pin, the refusal of a folder of step 5, -conversation-key and every refused call. Bring them:
git checkout step-6 -- '*_test.go'GOWORK=off go test ./...12What stays separate, and the limits
Each conversation has its own key, kolo-id, profile, rooms, logs, pin capability and invites. The name of a conversation is local. Members of two conversations cannot link you through your kolo-id, since you have a different one in each, but your computer's address and the timing of your connections still can.
Know the limits:
- No Leave in this step. The finished example has Leave, which removes one conversation from your computer: its folder, with its key, its logs, its invites and the kolo-id it used. The others are not told and keep what you sent, and your other conversations stay.
- No member removal. Nobody can remove a member or change a conversation's key, as in step 5. Revoking an invite stops new people, not those who joined.
- At most eight conversations, counting the join that waits. Each one costs one UDP socket, one DHT node, one swarm and two Pebble stores. The finished example makes the bound a setting, 64 by default.
- Old folders are refused. A data folder of step 5 is refused, never migrated, and nothing in it is changed.
- One fixed port, one conversation. With
-listenon a port other than 0, a second conversation is refused. - A second invite to the same conversation makes a second folder with a second kolo-id: the others see a new member.
Next steps
- Agree on who is in a conversation and which rooms it has: Step 7: Agree on members and rooms with kolo-braid.
- The finished example, kolo-chat-wails3-example, adds Leave, a setting for the bound, connection relays, the notch and the tray. Its
docs/how-it-works.md, section "Several conversations", tells how; itsdocs/security.mdhas the security notes. The finished example shows one list of rooms, one for each conversation, and its pin is optional: without one, messages reach people only while they are online. - Read the kolo-swarm page: one connection per peer key, and its topics.
- To compare your files with the finished ones, check out the tag
step-6of the starter repository.