Share general review and documentation rules

[onechat] / whatsapp.go

diff --git a/whatsapp.go b/whatsapp.go
index 05db5e415a22245457a5a019f78ee72d12d66ab3..27dd3c3e88a706ee2e6a18e4ad32930c522d736c 100644 (file)
--- a/whatsapp.go
+++ b/whatsapp.go
@@ -2,22 +2,27 @@ package main
 
 import (
        "context"
 
 import (
        "context"

+       "crypto/sha256"
+       "database/sql"

        "errors"
        "fmt"
        "errors"
        "fmt"

-       "log"
+       "log/slog"

        "net/url"
        "os"
        "path/filepath"
        "net/url"
        "os"
        "path/filepath"

+       "slices"

        "strings"
        "sync"
        "time"
 
        "go.mau.fi/whatsmeow"
        "strings"
        "sync"
        "time"
 
        "go.mau.fi/whatsmeow"

+       "go.mau.fi/whatsmeow/proto/waCompanionReg"
+       "go.mau.fi/whatsmeow/proto/waE2E"

        "go.mau.fi/whatsmeow/store"
        "go.mau.fi/whatsmeow/store/sqlstore"
        "go.mau.fi/whatsmeow/store"
        "go.mau.fi/whatsmeow/store/sqlstore"

+       "go.mau.fi/whatsmeow/types"

        "go.mau.fi/whatsmeow/types/events"
        waLog "go.mau.fi/whatsmeow/util/log"
        "go.mau.fi/whatsmeow/types/events"
        waLog "go.mau.fi/whatsmeow/util/log"

-

        // The session store of the library opens SQLite with this pure Go
        // driver.
        _ "modernc.org/sqlite"
        // The session store of the library opens SQLite with this pure Go
        // driver.
        _ "modernc.org/sqlite"


@@ -36,11 +41,45 @@ const (
        // as "/whatsapp status".
        whatsappCommand = "/whatsapp"
 
        // as "/whatsapp status".
        whatsappCommand = "/whatsapp"
 

-       // whatsappUsage is the answer to a WhatsApp command that does not exist.
-       whatsappUsage = "Use /whatsapp status."
+       // whatsappUsage is the answer to a WhatsApp command that does not
+       // exist.
+       whatsappUsage = "Use /whatsapp pair PHONE, /whatsapp status, or /whatsapp unlink. PHONE is the number of your WhatsApp account with its country code, such as +15550001111."
+
+       // whatsappPairSteps tells the user what to do with the pairing code,
+       // which comes in the next message.
+       whatsappPairSteps = "In WhatsApp on your phone, open Linked devices, tap Link a device, then tap Link with phone number instead, and enter the code of the next message. The code expires in about 2 minutes."
+
+       // whatsappPairExpired is the answer when the pairing code expires.
+       whatsappPairExpired = "The pairing code expired. Run /whatsapp pair PHONE again for a new code."

 
        // whatsappTimeLayout is the layout of the times in the answers.
        whatsappTimeLayout = "2006-01-02 15:04"
 
        // whatsappTimeLayout is the layout of the times in the answers.
        whatsappTimeLayout = "2006-01-02 15:04"

+
+       // whatsappPairTimeout is the longest time of a pairing. The library
+       // closes the pairing connection after about 160 seconds.
+       whatsappPairTimeout = 3 * time.Minute
+
+       // whatsappLogoutTimeout is the longest time of the logout call of an
+       // unlink.
+       whatsappLogoutTimeout = 30 * time.Second
+
+       // whatsappOutageNoticeDelay is the delay from a disconnection to its
+       // notice to the user.
+       whatsappOutageNoticeDelay = 10 * time.Minute
+
+       // whatsappRetryDelay is the first wait after a failed starting
+       // connection.
+       whatsappRetryDelay = 2 * time.Second
+
+       // whatsappRetryLimit is the longest wait between starting connections.
+       whatsappRetryLimit = 5 * time.Minute
+
+       // whatsappRequests is the number of pair and unlink commands that can
+       // wait for Run.
+       whatsappRequests = 8
+
+       // whatsappNotLinked is the answer of a WhatsApp tool without a link.
+       whatsappNotLinked = "WhatsApp is not linked. Tell the user to run /whatsapp pair PHONE in the terminal or in Telegram."

 )
 
 // WhatsAppClient is the part of the WhatsApp client that the daemon uses. The
 )
 
 // WhatsAppClient is the part of the WhatsApp client that the daemon uses. The


@@ -49,23 +88,121 @@ const (
 type WhatsAppClient interface {
        ConnectContext(ctx context.Context) error
        Disconnect()
 type WhatsAppClient interface {
        ConnectContext(ctx context.Context) error
        Disconnect()

+       GetQRChannel(ctx context.Context) (<-chan whatsmeow.QRChannelItem, error)
+       PairPhone(ctx context.Context, phone string, showPushNotification bool, clientType whatsmeow.PairClientType, clientDisplayName string) (string, error)
+       Logout(ctx context.Context) error
+       GetJoinedGroups(ctx context.Context) ([]*types.GroupInfo, error)
+       Download(ctx context.Context, message whatsmeow.DownloadableMessage) ([]byte, error)
+       Upload(ctx context.Context, data []byte, mediaType whatsmeow.MediaType) (whatsmeow.UploadResponse, error)
+       GenerateMessageID() types.MessageID
+       SendMessage(ctx context.Context, to types.JID, message *waE2E.Message, extra ...whatsmeow.SendRequestExtra) (whatsmeow.SendResponse, error)
+}
+
+// WhatsApp is the link of the daemon to the WhatsApp account of the user, as a
+// linked device. The session database of the library in dir holds the keys of
+// the device. Run keeps a linked device connected, and the library connects
+// again by itself after a network failure.
+//
+// The commands pair and unlink go to Run as requests, and Run runs one at a
+// time. A pairing runs in its own goroutine until its code expires, and a new
+// pairing ends the one before. Its phone number and code go only to the answer
+// of the client that asked. A logout from the phone comes as an event of the
+// library, and Run deletes the session. The mutex protects the session, the
+// client, and the state of the connection, which the event handler of the
+// library changes from its own goroutines. The sessionMutex serializes session
+// creation, close, removal, and snapshots. It is held before mutex, and stays
+// held when removal releases mutex for client callbacks.
+//
+// ctx is the caller context until Run sets its context for library callbacks.
+// The mutex protects it, so callbacks follow daemon cancellation.
+//
+// The inbox puts messages into batches and logs them, and groups holds the
+// names of the groups. Both get a WhatsAppLink from link for each call, so they
+// use the current device and client.
+//
+// The library logs nothing, because its log lines hold the ID of the own
+// account, which is the phone number of the user. The own number and the own
+// LID never go to the log of the agent or to the log of the daemon: redact
+// removes them from the errors, and a batch shows the messages of the user as
+// You and a mention of the user as @you. The IDs of the other chats go to the
+// log, and those of private chats hold phone numbers, because the agent needs
+// them to send.
+type WhatsApp struct {
+       ctx       context.Context
+       dir       string
+       clock     func() time.Time
+       logger    *slog.Logger
+       newClient func(device *store.Device, handle func(event any) bool) WhatsAppClient
+       requests  chan WhatsAppRequest
+       logouts   chan struct{}
+       state     *WhatsAppState
+       groups    *WhatsAppGroups
+       inbox     *WhatsAppInbox
+       routes    *Routes
+
+       sessionMutex   sync.Mutex
+       mutex          sync.Mutex
+       container      *sqlstore.Container
+       device         *store.Device
+       client         WhatsAppClient
+       linked         bool
+       own            []string
+       notify         func(Event)
+       connected      bool
+       retrying       bool
+       connectedAt    time.Time
+       disconnectedAt time.Time
+       disconnections int
+       noticed        bool
+       timer          *time.Timer
+       closed         bool
+}
+
+// WhatsAppLink is a copy of the link of the device at one time, for the parts
+// of WhatsApp that do not own it: the groups, the batches, find, and send.
+type WhatsAppLink struct {
+       linked    bool
+       device    *store.Device
+       client    WhatsAppClient
+       connected bool
+       own       []string
+}
+
+// WhatsAppRequest is a pair or unlink command for Run, with the function that
+// gives its answers to the client that asked. A pairing has the phone number.
+type WhatsAppRequest struct {
+       phone  string
+       unlink bool
+       answer func(text string)

 }
 
 // openWhatsApp opens the WhatsApp session in the data directory dir. Without
 // the session file, WhatsApp is not linked. The session gives full access to
 // the account, so a file that another user can read is an error. The clock
 // gives the times of the status, logger gets the failures, and newClient makes
 }
 
 // openWhatsApp opens the WhatsApp session in the data directory dir. Without
 // the session file, WhatsApp is not linked. The session gives full access to
 // the account, so a file that another user can read is an error. The clock
 // gives the times of the status, logger gets the failures, and newClient makes

-// the client of a linked device with its event handler.
-func openWhatsApp(ctx context.Context, dir string, clock func() time.Time, logger *log.Logger, newClient func(device *store.Device, handle func(event any) bool) WhatsAppClient) (*WhatsApp, error) {
+// the client of a device with its event handler.
+func openWhatsApp(ctx context.Context, dir string, clock func() time.Time, logger *slog.Logger, newClient func(device *store.Device, handle func(event any) bool) WhatsAppClient) (*WhatsApp, error) {

        w := &WhatsApp{
        w := &WhatsApp{

+               ctx:       ctx,

                dir:       filepath.Join(dir, whatsappDirName),
                clock:     clock,
                logger:    logger,
                newClient: newClient,
                dir:       filepath.Join(dir, whatsappDirName),
                clock:     clock,
                logger:    logger,
                newClient: newClient,

+               requests:  make(chan WhatsAppRequest, whatsappRequests),
+               logouts:   make(chan struct{}, 1),
+               groups:    newWhatsAppGroups(logger),
+       }
+
+       var err error
+
+       w.state, err = openWhatsAppState(filepath.Join(w.dir, whatsappStateFileName))
+       if err != nil {
+               return nil, fmt.Errorf("open WhatsApp state: %w", err)

        }
 
        }
 

-       path := filepath.Join(w.dir, whatsappSessionFileName)
-       info, err := os.Stat(path)
+       w.inbox = newWhatsAppInbox(w.state, clock, w.groups, &ImageStore{dir: filepath.Join(dir, imageDirName)}, logger)
+
+       info, err := os.Stat(w.sessionPath())

        if errors.Is(err, os.ErrNotExist) {
                return w, nil
        }
        if errors.Is(err, os.ErrNotExist) {
                return w, nil
        }


@@ -78,147 +215,874 @@ func openWhatsApp(ctx context.Context, dir string, clock func() time.Time, logge
                return nil, fmt.Errorf("%s holds the WhatsApp session, so its mode must be 0600", filepath.Join(whatsappDirName, whatsappSessionFileName))
        }
 
                return nil, fmt.Errorf("%s holds the WhatsApp session, so its mode must be 0600", filepath.Join(whatsappDirName, whatsappSessionFileName))
        }
 

-       address, err := whatsappSessionAddress(path)
+       err = w.openSession(ctx)

        if err != nil {
        if err != nil {

-               return nil, err
+               return nil, fmt.Errorf("open WhatsApp session: %w", err)
+       }
+
+       if w.device.ID != nil {
+               w.linked = true
+               w.inbox.waitForCatchup()
+
+               w.own = whatsappOwnIDs(w.device.ID.User, w.device.LID.User)

        }
 
        }
 

-       w.container, err = sqlstore.New(ctx, "sqlite", address, waLog.Noop)
+       return w, nil
+}
+
+func (w *WhatsApp) sessionPath() string {
+       return filepath.Join(w.dir, whatsappSessionFileName)
+}
+
+// openSession opens the session database and its first device. The caller holds
+// the mutex, or no other goroutine uses w yet.
+func (w *WhatsApp) openSession(ctx context.Context) error {
+       address, err := whatsappSessionAddress(w.sessionPath())

        if err != nil {
        if err != nil {

-               return nil, fmt.Errorf("open WhatsApp session: %w", err)
+               return fmt.Errorf("find WhatsApp session address: %w", err)

        }
 
        }
 

-       w.device, err = w.container.GetFirstDevice(ctx)
+       container, err := sqlstore.New(ctx, "sqlite", address, waLog.Noop)

        if err != nil {
        if err != nil {

-               return nil, errors.Join(fmt.Errorf("read WhatsApp device: %w", err), w.container.Close())
+               return fmt.Errorf("open WhatsApp session: %w", err)

        }
 
        }
 

-       return w, nil
+       device, err := container.GetFirstDevice(ctx)
+       if err != nil {
+               return errors.Join(fmt.Errorf("read WhatsApp device: %w", err), container.Close())
+       }
+
+       w.container = container
+       w.device = device
+
+       return nil

 }
 
 }
 

-// WhatsApp is the link of the daemon to the WhatsApp account of the user, as
-// a linked device. The session database of the library in dir holds the keys
-// of the device. A device with an ID is linked, and Run keeps it connected.
-// The library connects again by itself after a network failure. The mutex
-// protects the state of the connection, which the event handler of the library
-// changes from its own goroutines.
-//
-// The library logs nothing, because its log lines hold the ID of the own
-// account, which is the phone number of the user.
-type WhatsApp struct {
-       dir       string
-       clock     func() time.Time
-       logger    *log.Logger
-       newClient func(device *store.Device, handle func(event any) bool) WhatsAppClient
-       container *sqlstore.Container
-       device    *store.Device
-       client    WhatsAppClient
+// Run connects a linked device, logs the closed batches in l, runs the pair and
+// unlink commands, and handles a logout from the phone, until ctx ends. Its
+// notes go to the log of l, and notify gets the notices for all clients. A
+// failed first connection starts the same outage notice as a lost connection. A
+// timer in the select retries it with a doubled wait from 2 seconds to 5
+// minutes, without a retry goroutine or a wait that blocks commands or the
+// inbox. A connection, unlink, logout, or ctx end stops retries. The library
+// owns retries after a connection opens. Run returns the error of a write of
+// the log or of the state file, which stops the daemon, because then messages
+// would be lost.
+func (w *WhatsApp) Run(ctx context.Context, l *TurnLoop, notify func(Event)) error {
+       w.mutex.Lock()

 
 

-       mutex          sync.Mutex
-       connected      bool
-       connectedAt    time.Time
-       disconnectedAt time.Time
+       w.ctx = ctx
+       w.notify = notify
+       linked := w.linked
+       w.retrying = linked
+       w.mutex.Unlock()
+
+       timer := time.NewTimer(whatsappRetryDelay)
+       timer.Stop()
+       defer timer.Stop()
+
+       var retry <-chan time.Time
+
+       delay := whatsappRetryDelay
+       connect := func() {
+               retry = nil
+               if w.connect(ctx) {
+                       timer.Reset(delay)
+
+                       retry = timer.C
+                       delay = min(2*delay, whatsappRetryLimit)
+               }
+       }
+
+       stopRetry := func() {
+               timer.Stop()
+
+               retry = nil
+
+               w.mutex.Lock()
+
+               w.retrying = false
+               w.mutex.Unlock()
+       }
+
+       var pairing sync.WaitGroup
+
+       cancel := func() {
+       }
+
+       defer func() {
+               cancel()
+               pairing.Wait()
+               w.close()
+       }()
+
+       if linked {
+               connect()
+       }
+
+       for {
+               err := w.inbox.deliver(ctx, l, w.link(), false)
+               if err != nil {
+                       return fmt.Errorf("deliver WhatsApp inbox: %w", err)
+               }
+
+               select {
+               case <-ctx.Done():
+                       return nil
+               case err = <-w.inbox.failures:
+                       if err != nil {
+                               return fmt.Errorf("receive WhatsApp inbox: %w", err)
+                       }
+
+                       return nil
+               case <-w.inbox.wake:
+               case <-w.inbox.due():
+               case <-retry:
+                       connect()
+               case <-w.logouts:
+                       stopRetry()
+
+                       err = w.loggedOut(ctx, l)
+                       if err != nil {
+                               return fmt.Errorf("handle WhatsApp logout: %w", err)
+                       }
+               case request := <-w.requests:
+                       cancel()
+                       pairing.Wait()
+
+                       cancel = func() {
+                       }
+
+                       switch {
+                       case request.unlink:
+                               stopRetry()
+
+                               err = w.unlink(ctx, l, request.answer)
+                               if err != nil {
+                                       return fmt.Errorf("unlink WhatsApp: %w", err)
+                               }
+                       case w.isLinked():
+                               request.answer("WhatsApp is linked already. Run /whatsapp unlink first.")
+                       default:
+                               pairCtx, cancelPair := context.WithTimeout(ctx, whatsappPairTimeout)
+                               cancel = cancelPair
+                               pairing.Go(func() {
+                                       defer cancelPair()
+
+                                       w.pair(pairCtx, ctx, l, request.phone, request.answer)
+                               })
+                       }
+               }
+       }
+}
+
+// connect tries the starting connection of the linked device with one client.
+// It returns whether Run must retry. A failed call starts the shared outage
+// state and logs its redacted cause once, because a returned ConnectContext
+// error does not emit Disconnected. Connected logs recovery after
+// authentication.
+func (w *WhatsApp) connect(ctx context.Context) bool {
+       w.mutex.Lock()
+
+       if ctx.Err() != nil || !w.linked || !w.retrying || w.closed {
+               w.mutex.Unlock()
+
+               return false
+       }
+
+       if w.client == nil {
+               w.client = w.newClient(w.device, w.handle)
+       }
+
+       client := w.client
+       w.mutex.Unlock()
+
+       err := client.ConnectContext(ctx)
+
+       w.mutex.Lock()
+
+       if err == nil || ctx.Err() != nil || !w.retrying || !w.linked {
+               w.retrying = false
+               w.mutex.Unlock()
+
+               return false
+       }
+
+       first := w.startOutage()
+       cause := whatsappRedact(w.own, err.Error())
+       w.mutex.Unlock()
+
+       if first {
+               w.logger.Warn("first connect failed, retrying", "err", cause)
+       }
+
+       return true
+}
+
+// close ends the connection and the timer of the notice, and stops all notices.
+func (w *WhatsApp) close() {
+       w.mutex.Lock()
+
+       w.closed = true
+       if w.timer != nil {
+               w.timer.Stop()
+       }
+
+       client := w.client
+       w.client = nil
+       w.mutex.Unlock()
+
+       w.inbox.close()
+
+       if client != nil {
+               client.Disconnect()
+       }
+}
+
+// link returns a copy of the link of the device: whether it is linked, the
+// device, the client, whether it is connected, and the own IDs.
+func (w *WhatsApp) link() WhatsAppLink {
+       w.mutex.Lock()
+       defer w.mutex.Unlock()
+
+       return WhatsAppLink{
+               linked:    w.linked,
+               device:    w.device,
+               client:    w.client,
+               connected: w.connected,
+               own:       slices.Clone(w.own),
+       }
+}
+
+// loggedOut logs the open batches, deletes the session after a logout from the
+// phone, notes it in the log of l, and tells all clients one time.
+func (w *WhatsApp) loggedOut(ctx context.Context, l *TurnLoop) error {
+       if !w.isLinked() {
+               return nil
+       }
+
+       w.logger.Error("logged out by the phone")
+
+       err := w.inbox.deliver(ctx, l, w.link(), true)
+       if err != nil {
+               return err
+       }
+
+       err = w.removeSession()
+       if err != nil {
+               w.logger.Error("session delete failed", "err", err)
+       }
+
+       err = l.note("WhatsApp was unlinked from the phone.")
+       if err != nil {
+               w.logger.Error("chat note failed", "err", err)
+       }
+
+       w.broadcast("WhatsApp was unlinked from the phone. Run /whatsapp pair PHONE to link it again.")
+
+       return nil

 }
 
 }
 

-// Run connects a linked device and keeps the connection until ctx ends. A
-// failed first connection is logged, and the library tries again when the
-// failure is one of the network.
-func (w *WhatsApp) Run(ctx context.Context) {
-       if !w.linked() {
-               <-ctx.Done()
+// unlink logs the open batches, logs out the linked device, and deletes the
+// session. When the logout call fails, as it does while WhatsApp is
+// disconnected, the session is deleted all the same, and answer tells the user
+// to remove the device in the phone. Its error is one of the log or the state
+// file.
+func (w *WhatsApp) unlink(ctx context.Context, l *TurnLoop, answer func(text string)) error {
+       w.mutex.Lock()
+
+       linked := w.linked
+       client := w.client
+       w.mutex.Unlock()
+
+       if !linked {
+               answer("WhatsApp is not linked.")
+
+               return nil
+       }
+
+       err := w.inbox.deliver(ctx, l, w.link(), true)
+       if err != nil {
+               return err
+       }
+
+       var logoutErr error
+
+       if client != nil {
+               ctx, cancel := context.WithTimeout(ctx, whatsappLogoutTimeout)
+               defer cancel()
+
+               logoutErr = client.Logout(ctx)
+       }
+
+       err = w.removeSession()
+       if err != nil {
+               answer("The unlink failed: " + w.redact(err.Error()))
+
+               return nil
+       }
+
+       w.logger.Info("unlinked")
+
+       err = l.note("WhatsApp is unlinked.")
+       if err != nil {
+               w.logger.Error("chat note failed", "err", err)
+       }
+
+       if client == nil || logoutErr != nil {
+               answer("WhatsApp is unlinked here, but the phone did not get the logout. In WhatsApp on your phone, open Linked devices and remove the device.")
+
+               return nil
+       }
+
+       answer("WhatsApp is unlinked.")
+
+       return nil
+}
+
+func (w *WhatsApp) isLinked() bool {
+       w.mutex.Lock()
+       defer w.mutex.Unlock()
+
+       return w.linked
+}
+
+// pair links a new device to the account of phone with a pairing code. It gives
+// the steps and the code to answer, and then the end of the pairing: the linked
+// number, an expired code, or a failure. A pairing that a new one ends gives no
+// answer. A link notes "WhatsApp is linked." in the log of l, with no number.
+// The client of a pairing that does not link is disconnected.
+//
+// ctx limits the pairing, but the connection uses runCtx, the context of Run.
+// The library keeps the context of the connection for its keep-alive, its event
+// handler, and its reconnections, and after the link the server ends the stream
+// and the library connects again. With ctx, the end of the pairing would stop
+// that reconnection, and the linked device would never connect.
+func (w *WhatsApp) pair(ctx, runCtx context.Context, l *TurnLoop, phone string, answer func(text string)) {
+       device, err := w.newDevice(ctx)
+       if err != nil {
+               answer("The pairing failed: " + err.Error())
+

                return
        }
 
                return
        }
 

-       w.client = w.newClient(w.device, w.handle)
-       err := w.client.ConnectContext(ctx)
+       client := w.newClient(device, w.handle)
+       linked := false
+       defer func() {
+               if !linked {
+                       client.Disconnect()
+               }
+       }()
+
+       qr, err := client.GetQRChannel(ctx)
+       if err == nil {
+               err = client.ConnectContext(runCtx)
+       }
+

        if err != nil {
        if err != nil {

-               w.logger.Printf("connect: %v", err)
+               answer("The connection to WhatsApp failed: " + err.Error())
+
+               return
+       }
+
+       select {
+       case item, open := <-qr:
+               if !open || item.Event != whatsmeow.QRChannelEventCode {
+                       answer("WhatsApp did not start the pairing. Try again later.")
+
+                       return
+               }
+       case <-ctx.Done():
+               if errors.Is(ctx.Err(), context.DeadlineExceeded) {
+                       answer("The connection to WhatsApp did not start the pairing in time. Try again later.")
+               }
+
+               return
+       }
+
+       // The server accepts only a display name of the form "Browser (OS)"
+       // with a common browser and OS, and refuses the pairing otherwise.
+       code, err := client.PairPhone(ctx, phone, true, whatsmeow.PairClientChrome, "Chrome (Linux)")
+       if err != nil {
+               answer("WhatsApp refused the pairing: " + err.Error() + ". Check the phone number and run /whatsapp pair PHONE again.")
+
+               return
+       }
+
+       answer(whatsappPairSteps)
+       answer(code)
+
+       for {
+               var item whatsmeow.QRChannelItem
+
+               open := true
+               select {
+               case item, open = <-qr:
+               case <-ctx.Done():
+                       if errors.Is(ctx.Err(), context.DeadlineExceeded) {
+                               answer(whatsappPairExpired)
+                       }
+
+                       return
+               }
+
+               switch {
+               case !open || item.Event == whatsmeow.QRChannelTimeout.Event:
+                       answer(whatsappPairExpired)
+
+                       return
+               case item.Event == whatsmeow.QRChannelEventCode:
+                       continue
+               case item.Event == whatsmeow.QRChannelSuccess.Event:
+                       linked = true
+
+                       w.linkedBy(client)
+                       w.logger.Info("linked")
+
+                       err = l.note("WhatsApp is linked.")
+                       if err != nil {
+                               w.logger.Error("chat note failed", "err", err)
+                       }
+
+                       answer("WhatsApp is linked to +" + phone + ".")
+
+                       return
+               default:
+                       answer("The pairing failed: " + whatsappItemError(item) + ". Run /whatsapp pair PHONE again.")
+
+                       return
+               }
+       }
+}
+
+// handle takes one event of the library and tells if it was handled. A message
+// goes to the inbox. The names of the groups follow the events of the groups. A
+// connection starts a catch-up of the inbox, which ends at OfflineSyncCompleted
+// or after whatsappCatchupTimeout. A disconnection keeps the time of its start
+// while Run or the library tries again. After whatsappOutageNoticeDelay of a
+// disconnection, all clients get one notice, and they get one more when the
+// connection comes back. A disconnection that the library does not try again
+// gives a notice at once.
+//
+// The log of the daemon gets one line for each change of the connection of the
+// linked device: connected, a failed first connection, a lost connection, and
+// connected again with the length of the outage. The retries of the library and
+// Run between them log nothing.
+func (w *WhatsApp) handle(event any) bool {
+       w.mutex.Lock()
+
+       ctx := w.ctx
+       w.mutex.Unlock()
+
+       switch event := event.(type) {
+       case *events.Message:
+               return w.inbox.receive(ctx, w.link(), event)
+       case *events.GroupInfo:
+               if event.Name != nil {
+                       w.groups.set(event.JID.String(), event.Name.Name)
+               }
+
+               return true
+       case *events.JoinedGroup:
+               w.groups.set(event.JID.String(), event.Name)
+
+               return true
+       case *events.OfflineSyncCompleted:
+               w.inbox.endCatchup()
+
+               return true
+       case *events.Connected:
+               w.inbox.startCatchup()
+       }
+
+       var notice, line string
+
+       level := slog.LevelInfo
+
+       var attrs []any
+
+       w.mutex.Lock()
+
+       switch event := event.(type) {
+       case *events.PairSuccess:
+               w.own = whatsappOwnIDs(event.ID.User, event.LID.User)
+       case *events.Connected:
+               switch {
+               case !w.linked || w.connected:
+               case w.disconnectedAt.IsZero():
+                       line = "connected"
+               default:
+                       line = "connected again"
+                       attrs = append(attrs, "after", w.clock().Sub(w.disconnectedAt))
+               }
+
+               w.connected = true
+               w.retrying = false
+               w.connectedAt = w.clock()
+               if w.timer != nil {
+                       w.timer.Stop()
+               }
+
+               if w.noticed {
+                       w.noticed = false
+                       notice = "WhatsApp is connected again."
+               }
+       case *events.Disconnected:
+               connected := w.connected
+               if w.startOutage() {
+                       level = slog.LevelWarn
+                       line = "disconnected, retrying"
+                       if !connected {
+                               line = "first connect failed, retrying"
+                       }
+               }
+       case *events.LoggedOut:
+               w.retrying = false
+               select {
+               case w.logouts <- struct{}{}:
+               default:
+               }
+       case events.PermanentDisconnect:
+               w.retrying = false
+               if w.linked {
+                       w.connected = false
+                       w.noticed = true
+                       notice = "WhatsApp is disconnected and does not connect again by itself: " + event.PermanentDisconnectDescription() + ". Restart the daemon to try again."
+                       level = slog.LevelError
+                       line = "disconnected for good, restart to retry"
+                       attrs = append(attrs, "err", whatsappRedact(w.own, event.PermanentDisconnectDescription()))
+               }
+       }
+
+       if w.closed {
+               line = ""

        }
 
        }
 

-       <-ctx.Done()
-       w.client.Disconnect()
+       w.mutex.Unlock()
+
+       if line != "" {
+               w.logger.Log(ctx, level, line, attrs...)
+       }
+
+       if notice != "" {
+               w.broadcast(notice)
+       }
+
+       return true
+}
+
+// startOutage starts the shared outage time and notice timer once. The caller
+// holds the mutex. Its result tells whether this is the first failure.
+func (w *WhatsApp) startOutage() bool {
+       first := w.linked && (w.connected || w.disconnectedAt.IsZero())
+       if first {
+               w.disconnectedAt = w.clock()
+               w.disconnections++
+               disconnections := w.disconnections
+               w.timer = time.AfterFunc(whatsappOutageNoticeDelay, func() {
+                       w.disconnectedLong(disconnections)
+               })
+       }
+
+       w.connected = false
+
+       return first
+}
+
+// removeSession ends the connection, closes the session database, and deletes
+// its files. The session lock covers the cleanup after mutex is released, so a
+// snapshot or a new session cannot open files that cleanup removes.
+func (w *WhatsApp) removeSession() error {
+       w.sessionMutex.Lock()
+       defer w.sessionMutex.Unlock()
+
+       w.mutex.Lock()
+
+       client := w.client
+       w.client = nil
+       w.linked = false
+       w.retrying = false
+       w.own = nil
+       w.connected = false
+       w.disconnectedAt = time.Time{}
+       if w.timer != nil {
+               w.timer.Stop()
+       }
+
+       w.noticed = false
+       container := w.container
+       w.container = nil
+       w.device = nil
+       w.mutex.Unlock()
+
+       w.inbox.stopCatchup()
+
+       if client != nil {
+               client.Disconnect()
+       }
+
+       var err error
+
+       if container != nil {
+               err = container.Close()
+       }
+
+       for _, suffix := range []string{"", "-wal", "-shm"} {
+               removeErr := os.Remove(w.sessionPath() + suffix)
+               if !errors.Is(removeErr, os.ErrNotExist) {
+                       err = errors.Join(err, removeErr)
+               }
+       }
+
+       return err
+}
+
+// broadcast gives text as a notice to all clients.
+func (w *WhatsApp) broadcast(text string) {
+       w.mutex.Lock()
+
+       notify := w.notify
+       closed := w.closed
+       w.mutex.Unlock()
+
+       if notify != nil && !closed {
+               notify(Event{
+                       Kind: "notice",
+                       Text: text,
+               })
+       }
+}
+
+// redact replaces the own number and the own LID in text with OWN.
+func (w *WhatsApp) redact(text string) string {
+       w.mutex.Lock()
+       defer w.mutex.Unlock()
+
+       return whatsappRedact(w.own, text)
+}
+
+// newDevice returns a new device in the session database. It makes the
+// directory and the file of the session first, with their modes, when they do
+// not exist.
+func (w *WhatsApp) newDevice(ctx context.Context) (*store.Device, error) {
+       w.sessionMutex.Lock()
+       defer w.sessionMutex.Unlock()
+
+       w.mutex.Lock()
+       defer w.mutex.Unlock()
+
+       if w.container == nil {
+               err := os.MkdirAll(w.dir, 0o700)
+               if err != nil {
+                       return nil, fmt.Errorf("create WhatsApp directory: %w", err)
+               }
+
+               file, err := os.OpenFile(w.sessionPath(), os.O_CREATE|os.O_RDWR, 0o600)
+               if err != nil {
+                       return nil, fmt.Errorf("create WhatsApp session: %w", err)
+               }
+
+               err = file.Close()
+               if err != nil {
+                       return nil, fmt.Errorf("create WhatsApp session: %w", err)
+               }
+
+               err = w.openSession(ctx)
+               if err != nil {
+                       return nil, fmt.Errorf("open new WhatsApp session: %w", err)
+               }
+       }
+
+       w.device = w.container.NewDevice()
+
+       return w.device, nil
+}
+
+// linkedBy makes client the client of the linked device.
+func (w *WhatsApp) linkedBy(client WhatsAppClient) {
+       w.mutex.Lock()
+       defer w.mutex.Unlock()
+
+       w.client = client
+       w.linked = true
+}
+
+// disconnectedLong gives the notice of a long disconnection, unless the
+// disconnection with the number disconnections ended.
+func (w *WhatsApp) disconnectedLong(disconnections int) {
+       w.mutex.Lock()
+
+       long := !w.closed && w.linked && !w.connected && !w.noticed && w.disconnections == disconnections
+       if long {
+               w.noticed = true
+       }
+
+       since := w.disconnectedAt
+       w.mutex.Unlock()
+
+       if long {
+               w.broadcast("WhatsApp is disconnected since " + since.Format(whatsappTimeLayout) + ". OneChat tries again.")
+       }

 }
 
 // Command runs the WhatsApp command args, the text after /whatsapp, and gives
 // each answer to answer. The answers go only to the client that sent the
 // command.
 func (w *WhatsApp) Command(args string, answer func(text string)) {
 }
 
 // Command runs the WhatsApp command args, the text after /whatsapp, and gives
 // each answer to answer. The answers go only to the client that sent the
 // command.
 func (w *WhatsApp) Command(args string, answer func(text string)) {

-       switch strings.TrimSpace(args) {
-       case "status":
+       fields := strings.Fields(args)
+       request := WhatsAppRequest{
+               answer: answer,
+       }
+
+       switch {
+       case len(fields) == 1 && fields[0] == "status":

                answer(w.Status())
                answer(w.Status())

+
+               return
+       case len(fields) == 1 && fields[0] == "unlink":
+               request.unlink = true
+       case len(fields) >= 2 && fields[0] == "pair":
+               phone, valid := whatsappPhone(strings.Join(fields[1:], ""))
+               if !valid {
+                       answer("PHONE must be the number of your WhatsApp account with its country code: 7 to 15 digits, such as +15550001111.")
+
+                       return
+               }
+
+               request.phone = phone

        default:
                answer(whatsappUsage)
        default:
                answer(whatsappUsage)

+
+               return
+       }
+
+       select {
+       case w.requests <- request:
+       default:
+               answer("Too many WhatsApp commands wait. Try again in a minute.")

        }
 }
 
 // Status returns the state of the link: not linked, linked and connected, or
        }
 }
 
 // Status returns the state of the link: not linked, linked and connected, or

-// linked and disconnected, with the times of the connection. It never holds
-// the phone number.
+// linked and disconnected, with the times of the connection and the routes.
+// Route source IDs can hold the phone numbers of other chats.

 func (w *WhatsApp) Status() string {
        w.mutex.Lock()
        defer w.mutex.Unlock()
 
 func (w *WhatsApp) Status() string {
        w.mutex.Lock()
        defer w.mutex.Unlock()
 

+       routes := ""
+       if w.routes != nil {
+               listed := w.routes.List()
+               if listed != "No routes." {
+                       routes = "\nWhatsApp routes:\n" + listed
+               }
+       }
+

        switch {
        switch {

-       case !w.linked():
-               return "WhatsApp is not linked."
+       case !w.linked:
+               return "WhatsApp is not linked. Run /whatsapp pair PHONE to link it." + routes

        case w.connected:
        case w.connected:

-               return "WhatsApp is linked and connected since " + w.connectedAt.Format(whatsappTimeLayout) + "."
+               return "WhatsApp is linked and connected since " + w.connectedAt.Format(whatsappTimeLayout) + "." + routes

        case w.disconnectedAt.IsZero():
        case w.disconnectedAt.IsZero():

-               return "WhatsApp is linked and not connected yet."
+               return "WhatsApp is linked and not connected yet." + routes

        case w.connectedAt.IsZero():
        case w.connectedAt.IsZero():

-               return "WhatsApp is linked and disconnected since " + w.disconnectedAt.Format(whatsappTimeLayout) + "."
+               return "WhatsApp is linked and disconnected since " + w.disconnectedAt.Format(whatsappTimeLayout) + "." + routes

        default:
        default:

-               return "WhatsApp is linked and disconnected since " + w.disconnectedAt.Format(whatsappTimeLayout) + ". The last connection started at " + w.connectedAt.Format(whatsappTimeLayout) + "."
+               return "WhatsApp is linked and disconnected since " + w.disconnectedAt.Format(whatsappTimeLayout) + ". The last connection started at " + w.connectedAt.Format(whatsappTimeLayout) + "." + routes

        }
 }
 
        }
 }
 

-// Close closes the session database.
-func (w *WhatsApp) Close() error {
-       if w.container == nil {
+// BackupSession writes a consistent SQLite snapshot to path while the session
+// cannot be created, closed, or removed. The source opens without creation
+// permission. No session file means no linked state to copy.
+func (w *WhatsApp) BackupSession(ctx context.Context, path string) (err error) {
+       w.sessionMutex.Lock()
+       defer w.sessionMutex.Unlock()
+
+       w.mutex.Lock()
+       defer w.mutex.Unlock()
+
+       _, err = os.Stat(w.sessionPath())
+       if errors.Is(err, os.ErrNotExist) {

                return nil
        }
 
                return nil
        }
 

-       return w.container.Close()
-}
+       if err != nil {
+               return fmt.Errorf("read session file: %w", err)
+       }
+
+       err = os.MkdirAll(filepath.Dir(path), 0o700)
+       if err != nil {
+               return fmt.Errorf("create session snapshot directory: %w", err)
+       }
+
+       address, err := whatsappSessionAddress(w.sessionPath())
+       if err != nil {
+               return fmt.Errorf("find session database: %w", err)
+       }
+
+       database, err := sql.Open("sqlite", address+"&mode=rw")
+       if err != nil {
+               return fmt.Errorf("open session snapshot source: %w", err)
+       }
+
+       defer func() {
+               err = errors.Join(err, database.Close())
+       }()
+
+       _, err = database.ExecContext(ctx, "VACUUM INTO ?", path)
+       if err != nil {
+               return fmt.Errorf("snapshot session database: %w", err)
+       }

 
 

-// linked tells if the session holds a linked device.
-func (w *WhatsApp) linked() bool {
-       return w.device != nil && w.device.ID != nil
+       err = os.Chmod(path, 0o600)
+       if err != nil {
+               return fmt.Errorf("set session snapshot mode: %w", err)
+       }
+
+       return nil

 }
 
 }
 

-// handle takes one event of the library and tells if it was handled. A
-// disconnection keeps the time of its start while the library tries again.
-func (w *WhatsApp) handle(event any) bool {
+// Close closes the session database.
+func (w *WhatsApp) Close() error {
+       w.sessionMutex.Lock()
+       defer w.sessionMutex.Unlock()
+

        w.mutex.Lock()
        defer w.mutex.Unlock()
 
        w.mutex.Lock()
        defer w.mutex.Unlock()
 

-       switch event.(type) {
-       case *events.Connected:
-               w.connected = true
-               w.connectedAt = w.clock()
-       case *events.Disconnected:
-               if w.connected || w.disconnectedAt.IsZero() {
-                       w.disconnectedAt = w.clock()
-               }
-
-               w.connected = false
+       if w.container == nil {
+               return nil

        }
 
        }
 

-       return true
+       err := w.container.Close()
+       w.container = nil
+
+       return err

 }
 
 }
 

-// whatsappNewClient returns the client of the library for device, with handle
-// as its event handler. The client tries again after a failed first
-// connection, acknowledges a message only after handle returns true, and
-// downloads no old history.
-func whatsappNewClient(device *store.Device, handle func(event any) bool) WhatsAppClient {
-       client := whatsmeow.NewClient(device, waLog.Noop)
-       client.InitialAutoReconnect = true
-       client.SynchronousAck = true
-       client.ManualHistorySyncDownload = true
-       client.AddEventHandlerWithSuccessStatus(handle)
+// Find returns the answer of whatsapp_find for name, as whatsappFind says.
+func (w *WhatsApp) Find(ctx context.Context, name string) (string, error) {
+       return whatsappFind(ctx, w.link(), w.groups, name)
+}

 
 

-       return client
+// Send returns the answer of whatsapp_send for text and an optional stored
+// image to chat, with the durable send id that whatsappSend describes.
+func (w *WhatsApp) Send(ctx context.Context, id, chat, text, image string) (string, error) {
+       return whatsappSend(ctx, w.link(), w.groups, w.state, w.inbox.images, w.logger, w.clock, id, chat, text, image)
+}
+
+// whatsappOwnIDs returns the own number and the own LID that are not empty.
+func whatsappOwnIDs(ids ...string) []string {
+       var own []string
+
+       for _, id := range ids {
+               if id != "" {
+                       own = append(own, id)
+               }
+       }
+
+       return own

 }
 
 // whatsappSessionAddress returns the SQLite address of the session database at
 }
 
 // whatsappSessionAddress returns the SQLite address of the session database at


@@ -239,6 +1103,110 @@ func whatsappSessionAddress(path string) (string, error) {
        return address.String(), nil
 }
 
        return address.String(), nil
 }
 

+// whatsappRedact replaces each of the own IDs own in text with OWN.
+func whatsappRedact(own []string, text string) string {
+       for _, id := range own {
+               text = strings.ReplaceAll(text, id, "OWN")
+       }
+
+       return text
+}
+
+// whatsappItemError returns the error of a pairing item that is not a code, a
+// success, or a timeout.
+func whatsappItemError(item whatsmeow.QRChannelItem) string {
+       if item.Error != nil {
+               return item.Error.Error()
+       }
+
+       return item.Event
+}
+
+// whatsappPhone returns the digits of phone, a number with its country code and
+// an optional + and dashes, and tells if it has the form of a number: 7 to 15
+// digits, with no 0 first.
+func whatsappPhone(phone string) (string, bool) {
+       phone = strings.ReplaceAll(strings.TrimPrefix(phone, "+"), "-", "")
+       valid := len(phone) >= 7 && len(phone) <= 15 && phone[0] != '0' && strings.Trim(phone, "0123456789") == ""
+
+       return phone, valid
+}
+
+// whatsappSetDeviceProps sets the device properties that the library sends at
+// the pairing. They are global values of the library, so the daemon sets them
+// once before any client exists. The phone shows the linked device with the
+// name OneChat and a desktop icon only when the platform type is known.
+func whatsappSetDeviceProps() {
+       store.SetOSInfo("OneChat", [3]uint32{0, 1, 0})
+
+       store.DeviceProps.PlatformType = waCompanionReg.DeviceProps_DESKTOP.Enum()
+}
+
+// whatsappNewClient returns the client of the library for device, with handle
+// as its event handler. Run owns failed starting connections of linked devices,
+// so only an unlinked device enables the initial retry of the library for
+// pairing. The library still retries a lost connection. The client acknowledges
+// a message only after handle returns true, and downloads no old history.
+func whatsappNewClient(device *store.Device, handle func(event any) bool) WhatsAppClient {
+       client := whatsmeow.NewClient(device, waLog.Noop)
+       client.InitialAutoReconnect = device.ID == nil
+       client.SynchronousAck = true
+       client.ManualHistorySyncDownload = true
+       client.AddEventHandlerWithSuccessStatus(handle)
+
+       return client
+}
+
+// whatsappContactName returns the name of the person jid: the full name, the
+// first name, the business name, or the push name of the contact in the session
+// of device, then push, the push name of a message, then the phone number. A
+// LID gets its phone number from the LID map of the session.
+func whatsappContactName(ctx context.Context, device *store.Device, jid types.JID, push string) string {
+       jid = jid.ToNonAD()
+       candidates := []types.JID{jid}
+       phone := types.EmptyJID
+       switch jid.Server {
+       case types.DefaultUserServer:
+               phone = jid
+       case types.HiddenUserServer:
+               mapped, err := device.LIDs.GetPNForLID(ctx, jid)
+               if err == nil && !mapped.IsEmpty() {
+                       phone = mapped
+                       candidates = append(candidates, mapped)
+               }
+       }
+
+       for _, candidate := range candidates {
+               contact, err := device.Contacts.GetContact(ctx, candidate)
+               if err != nil || !contact.Found {
+                       continue
+               }
+
+               for _, name := range []string{contact.FullName, contact.FirstName, contact.BusinessName, contact.PushName} {
+                       if name != "" {
+                               return name
+                       }
+               }
+       }
+
+       switch {
+       case push != "":
+               return push
+       case !phone.IsEmpty():
+               return "+" + phone.User
+       default:
+               return jid.User
+       }
+}
+
+// whatsappChatHash returns a short hash of chat for the daemon log, so that a
+// log line can tell chats apart without a phone number.
+func whatsappChatHash(chat types.JID) string {
+       digest := sha256.Sum256([]byte(chat.ToNonAD().String()))
+
+       return fmt.Sprintf("%x", digest[:6])
+}
+

 // whatsappCommandArgs returns the text after /whatsapp of a line of a WhatsApp
 // command, or false for any other line.
 func whatsappCommandArgs(line string) (string, bool) {
 // whatsappCommandArgs returns the text after /whatsapp of a line of a WhatsApp
 // command, or false for any other line.
 func whatsappCommandArgs(line string) (string, bool) {