Release HyperMeow v0.1.0

.gitattributes

@@ -1,3 +1,4 @@
 *.pb.go linguist-generated=true
 *.pb.raw binary linguist-generated=true
 internals.go linguist-generated=true
+*.patch -whitespace

.github/workflows/go.yml

@@ -22,6 +22,9 @@ jobs:
       with:
         go-version: ${{ matrix.go-version }}
 
+    - name: Check generated MEX bindings
+      run: go run ./internal/cmd/genmex -input mex/spec.json -output mex/bindings.go -check
+
     - name: Build
       run: go build -v ./...
 

.pre-commit-config.yaml

@@ -4,10 +4,11 @@ repos:
     hooks:
       - id: trailing-whitespace
         exclude_types: [markdown]
-        exclude: LICENSE
+        exclude: '(^LICENSE$|\.patch$)'
       - id: end-of-file-fixer
         exclude: LICENSE
       - id: check-yaml
+        exclude: ^benchmark/barback/compose\.(dm|local-cache)\.yaml$
       - id: check-added-large-files
 
   - repo: https://github.com/tekwizely/pre-commit-golang
@@ -16,7 +17,7 @@ repos:
       - id: go-imports-repo
         args:
           - "-local"
-          - "go.mau.fi/whatsmeow"
+          - "github.com/polymorfa/hypermeow"
           - "-w"
       - id: go-vet-repo-mod
       # TODO enable this

README.md

@@ -3,6 +3,56 @@
 
 HyperMeow is a library used at Polymorfa to ship WhatsApp at scale. We forked from tulir's project since these performance changes are somewhat experimental and diverge from tulir's minimalist philosophy. For Polymorfa to succeed, we needed all the WhatsApp Web functions in one place, meanwhile tulir prefers the core functionalities / messaging be the scope of whatsmeow.
 
+HyperMeow is its own Go module, imported directly as `github.com/polymorfa/hypermeow`. It no longer requires a `replace` directive:
+
+```go
+import whatsmeow "github.com/polymorfa/hypermeow"
+```
+
+```sh
+go get github.com/polymorfa/hypermeow
+```
+
+### The module is `hypermeow`, the package is `whatsmeow`
+
+Only the *module path* moved. The Go *package* names are unchanged from upstream, so the root package is still declared `package whatsmeow`. Both of these are expected:
+
+- godoc renders the title as **"whatsmeow package - github.com/polymorfa/hypermeow"**;
+- the import path's last element (`hypermeow`) does not match the package name (`whatsmeow`), so import the root package under an explicit alias as shown above.
+
+This is deliberate. Keeping the upstream package names means no call site changes when migrating - `whatsmeow.Client`, `whatsmeow.NewClient` and friends all still resolve - and merges from tulir's upstream do not conflict on the package clause of every file. Sub-packages are unaffected, since their path element already matches their package name (`.../store` is `package store`, and so on).
+
+### Only one whatsmeow may be linked into a binary
+
+HyperMeow keeps upstream's generated protobuf descriptor paths (`waCommon/WACommon.proto` and friends) and their symbol namespaces. Those are registered in a process-global registry, so linking HyperMeow **and** upstream `go.mau.fi/whatsmeow` into the same binary panics before `main`:
+
+```
+proto: file "waCommon/WACommon.proto" is already registered
+```
+
+The old `replace` arrangement made this impossible, because both import paths resolved to one module. A distinct module path removes that guarantee, so a partially migrated dependency graph — where one of your dependencies still requires `go.mau.fi/whatsmeow` — is not safe.
+
+The failure is loud and immediate rather than silent, but it surfaces at process start. Check for it at build time instead:
+
+```sh
+go mod why -m go.mau.fi/whatsmeow   # should report the module is not needed
+```
+
+Use `-m`. Without it, `go mod why` asks about the *package* `go.mau.fi/whatsmeow`, and a dependency that imports only a subpackage — say `go.mau.fi/whatsmeow/proto/waCommon` — makes it answer "main module does not need package" while the upstream module is linked and its descriptors still collide.
+
+A stricter check inspects the link graph directly:
+
+```sh
+deps="$(go list -deps -test ./...)" || exit 1
+case "$deps" in *go.mau.fi/whatsmeow*) exit 1 ;; esac
+```
+
+Exit 0 means safe. There is deliberately no pipeline and no external command here. `-test` matters because `go list -deps` omits test-only dependencies, and a project importing upstream only from a `_test.go` still links both copies under `go test`. Capturing the output first means a failed `go list` propagates through `||` instead of being mistaken for an empty result, and matching with `case` avoids `grep`, whose exit status is 0 on a match — so a naive form of this check passes precisely when the graph is unsafe.
+
+or assert it in a test via `debug.ReadBuildInfo()`, failing if any entry in `Deps` reports the module path `go.mau.fi/whatsmeow`.
+
+Migrating from the previous `replace go.mau.fi/whatsmeow => github.com/polymorfa/hypermeow` setup: drop the `replace` line, add a normal `require` on `github.com/polymorfa/hypermeow`, and rewrite `go.mau.fi/whatsmeow` import paths to `github.com/polymorfa/hypermeow`. A `replace` directive is only honoured in the main module, so the previous arrangement did not carry to anything that depended on your module in turn; a direct requirement does.
+
 The reproducible Barback and PostgreSQL benchmark is documented in [`benchmark/barback`](benchmark/barback/README.md).
 
 ## Discussion

appstate.go

@@ -17,13 +17,13 @@ import (
 	"go.mau.fi/util/exslices"
 	"go.mau.fi/util/ptr"
 
-	"go.mau.fi/whatsmeow/appstate"
-	waBinary "go.mau.fi/whatsmeow/binary"
-	"go.mau.fi/whatsmeow/proto/waE2E"
-	"go.mau.fi/whatsmeow/proto/waServerSync"
-	"go.mau.fi/whatsmeow/store"
-	"go.mau.fi/whatsmeow/types"
-	"go.mau.fi/whatsmeow/types/events"
+	"github.com/polymorfa/hypermeow/appstate"
+	waBinary "github.com/polymorfa/hypermeow/binary"
+	"github.com/polymorfa/hypermeow/proto/waE2E"
+	"github.com/polymorfa/hypermeow/proto/waServerSync"
+	"github.com/polymorfa/hypermeow/store"
+	"github.com/polymorfa/hypermeow/types"
+	"github.com/polymorfa/hypermeow/types/events"
 )
 
 // FetchAppState fetches updates to the given type of app state. If fullSync is true, the current
@@ -67,7 +67,7 @@ func (cli *Client) fetchAppState(ctx context.Context, name appstate.WAPatchName,
 	wantSnapshot := fullSync
 	var eventsToDispatch []any
 	eventsToDispatchPtr := &eventsToDispatch
-	if fullSync && !cli.EmitAppStateEventsOnFullSync {
+	if fullSync && !cli.EmitAppStateEventsOnFullSync && !cli.EmitLabelEventsOnFullSync && !cli.EmitQuickReplyEventsOnFullSync {
 		eventsToDispatchPtr = nil
 	}
 	for hasMore {
@@ -108,7 +108,7 @@ func (cli *Client) handleAppStateRecovery(
 	}
 	var eventsToDispatch []any
 	eventsToDispatchPtr := &eventsToDispatch
-	if !cli.EmitAppStateEventsOnFullSync {
+	if !cli.EmitAppStateEventsOnFullSync && !cli.EmitLabelEventsOnFullSync && !cli.EmitQuickReplyEventsOnFullSync {
 		eventsToDispatchPtr = nil
 	}
 	snapshot, err := appstate.ParseRecovery(result[0].GetSyncdSnapshotFatalRecoveryResponse())
@@ -186,28 +186,62 @@ func (cli *Client) collectEventsToDispatch(
 		}
 	}
 	for _, mutation := range mutations {
-		if eventsToDispatch != nil && mutation.Operation == waServerSync.SyncdMutation_SET {
+		emitMutation := eventsToDispatch != nil && (!fullSync || cli.shouldEmitFullSyncMutation(mutation.Index))
+		if emitMutation && mutation.Operation == waServerSync.SyncdMutation_SET {
 			*eventsToDispatch = append(*eventsToDispatch, &events.AppState{Index: mutation.Index, SyncActionValue: mutation.Action})
 		}
 		evt := cli.dispatchAppState(ctx, name, mutation, fullSync)
-		if eventsToDispatch != nil && evt != nil {
+		if emitMutation && evt != nil {
 			*eventsToDispatch = append(*eventsToDispatch, evt)
 		}
 	}
 	return nil
 }
 
+func (cli *Client) shouldEmitFullSyncMutation(index []string) bool {
+	if cli.EmitAppStateEventsOnFullSync {
+		return true
+	}
+	if len(index) == 0 {
+		return false
+	}
+	if cli.EmitQuickReplyEventsOnFullSync && index[0] == appstate.IndexQuickReply {
+		return true
+	}
+	if !cli.EmitLabelEventsOnFullSync {
+		return false
+	}
+	switch index[0] {
+	case appstate.IndexLabelEdit, appstate.IndexLabelAssociationChat, appstate.IndexLabelAssociationMessage:
+		return true
+	default:
+		return false
+	}
+}
+
 func (cli *Client) filterContacts(mutations []appstate.Mutation) ([]appstate.Mutation, []store.ContactEntry) {
 	filteredMutations := mutations[:0]
 	contacts := make([]store.ContactEntry, 0, len(mutations))
 	for _, mutation := range mutations {
-		if mutation.Index[0] == "contact" && len(mutation.Index) > 1 {
+		if len(mutation.Index) > 1 && mutation.Index[0] == appstate.IndexContact {
 			jid, _ := types.ParseJID(mutation.Index[1])
 			act := mutation.Action.GetContactAction()
 			contacts = append(contacts, store.ContactEntry{
-				JID:       jid,
-				FirstName: act.GetFirstName(),
-				FullName:  act.GetFullName(),
+				JID:         jid,
+				FirstName:   act.GetFirstName(),
+				FullName:    act.GetFullName(),
+				Username:    act.GetUsername(),
+				UsernameSet: true,
+			})
+		} else if len(mutation.Index) > 1 && mutation.Index[0] == appstate.IndexLIDContact {
+			jid, _ := types.ParseJID(mutation.Index[1])
+			act := mutation.Action.GetLidContactAction()
+			contacts = append(contacts, store.ContactEntry{
+				JID:         jid,
+				FirstName:   act.GetFirstName(),
+				FullName:    act.GetFullName(),
+				Username:    act.GetUsername(),
+				UsernameSet: true,
 			})
 		} else {
 			filteredMutations = append(filteredMutations, mutation)
@@ -291,6 +325,18 @@ func (cli *Client) dispatchAppState(ctx context.Context, name appstate.WAPatchNa
 		eventToDispatch = &events.Contact{JID: jid, Timestamp: ts, Action: act, FromFullSync: fullSync}
 		if cli.Store.Contacts != nil {
 			storeUpdateError = cli.Store.Contacts.PutContactName(ctx, jid, act.GetFirstName(), act.GetFullName())
+			if usernameStore, ok := cli.Store.Contacts.(store.ContactUsernameStore); ok && storeUpdateError == nil {
+				storeUpdateError = usernameStore.PutContactUsername(ctx, jid, act.GetUsername())
+			}
+		}
+	case appstate.IndexLIDContact:
+		act := mutation.Action.GetLidContactAction()
+		eventToDispatch = &events.LIDContact{JID: jid, Timestamp: ts, Action: act, FromFullSync: fullSync}
+		if cli.Store.Contacts != nil {
+			storeUpdateError = cli.Store.Contacts.PutContactName(ctx, jid, act.GetFirstName(), act.GetFullName())
+			if usernameStore, ok := cli.Store.Contacts.(store.ContactUsernameStore); ok && storeUpdateError == nil {
+				storeUpdateError = usernameStore.PutContactUsername(ctx, jid, act.GetUsername())
+			}
 		}
 	case appstate.IndexClearChat:
 		act := mutation.Action.GetClearChatAction()
@@ -417,6 +463,16 @@ func (cli *Client) dispatchAppState(ctx context.Context, name appstate.WAPatchNa
 			Action:       act,
 			FromFullSync: fullSync,
 		}
+	case appstate.IndexQuickReply:
+		if len(mutation.Index) < 2 {
+			return
+		}
+		eventToDispatch = &events.QuickReply{
+			Timestamp:    ts,
+			ID:           mutation.Index[1],
+			Action:       mutation.Action.GetQuickReplyAction(),
+			FromFullSync: fullSync,
+		}
 	}
 	if storeUpdateError != nil {
 		cli.Log.Errorf("Failed to update device store after app state mutation: %v", storeUpdateError)

appstate/decode.go

@@ -17,11 +17,11 @@ import (
 
 	"google.golang.org/protobuf/proto"
 
-	waBinary "go.mau.fi/whatsmeow/binary"
-	"go.mau.fi/whatsmeow/proto/waServerSync"
-	"go.mau.fi/whatsmeow/proto/waSyncAction"
-	"go.mau.fi/whatsmeow/store"
-	"go.mau.fi/whatsmeow/util/cbcutil"
+	waBinary "github.com/polymorfa/hypermeow/binary"
+	"github.com/polymorfa/hypermeow/proto/waServerSync"
+	"github.com/polymorfa/hypermeow/proto/waSyncAction"
+	"github.com/polymorfa/hypermeow/store"
+	"github.com/polymorfa/hypermeow/util/cbcutil"
 )
 
 // PatchList represents a decoded response to getting app state patches from the WhatsApp servers.

appstate/encode.go

@@ -9,11 +9,11 @@ import (
 
 	"google.golang.org/protobuf/proto"
 
-	"go.mau.fi/whatsmeow/proto/waCommon"
-	"go.mau.fi/whatsmeow/proto/waServerSync"
-	"go.mau.fi/whatsmeow/proto/waSyncAction"
-	"go.mau.fi/whatsmeow/types"
-	"go.mau.fi/whatsmeow/util/cbcutil"
+	"github.com/polymorfa/hypermeow/proto/waCommon"
+	"github.com/polymorfa/hypermeow/proto/waServerSync"
+	"github.com/polymorfa/hypermeow/proto/waSyncAction"
+	"github.com/polymorfa/hypermeow/types"
+	"github.com/polymorfa/hypermeow/util/cbcutil"
 )
 
 // MutationInfo contains information about a single mutation to the app state.
@@ -162,6 +162,26 @@ func BuildLabelChat(target types.JID, labelID string, labeled bool) PatchInfo {
 	}
 }
 
+type LabelChatChange struct {
+	LabelID string
+	Labeled bool
+}
+
+func BuildLabelChatChanges(target types.JID, changes []LabelChatChange) PatchInfo {
+	mutations := make([]MutationInfo, 0, len(changes))
+	mutationIndexes := make(map[string]int, len(changes))
+	for _, change := range changes {
+		mutation := newLabelChatMutation(target, change.LabelID, change.Labeled)
+		if index, exists := mutationIndexes[change.LabelID]; exists {
+			mutations[index] = mutation
+		} else {
+			mutationIndexes[change.LabelID] = len(mutations)
+			mutations = append(mutations, mutation)
+		}
+	}
+	return PatchInfo{Type: WAPatchRegular, Mutations: mutations}
+}
+
 func newLabelMessageMutation(target types.JID, labelID, messageID string, labeled bool) MutationInfo {
 	return MutationInfo{
 		Index:   []string{IndexLabelAssociationMessage, labelID, target.String(), messageID, "0", "0"},
@@ -208,6 +228,43 @@ func BuildLabelEdit(labelID string, labelName string, labelColor int32, deleted
 	}
 }
 
+func newQuickReplyMutation(id, shortcut, message string, keywords []string, count int32, deleted bool, associatedLabelIDs []string) MutationInfo {
+	return MutationInfo{
+		Index:   []string{IndexQuickReply, id},
+		Version: 2,
+		Value: &waSyncAction.SyncActionValue{
+			QuickReplyAction: &waSyncAction.QuickReplyAction{
+				Shortcut:           proto.String(shortcut),
+				Message:            proto.String(message),
+				Keywords:           keywords,
+				Count:              proto.Int32(count),
+				Deleted:            proto.Bool(deleted),
+				AssociatedLabelIDs: associatedLabelIDs,
+			},
+		},
+	}
+}
+
+// BuildQuickReply builds an app state patch for adding or editing a quick reply.
+func BuildQuickReply(id, shortcut, message string, keywords []string, count int32, associatedLabelIDs ...string) PatchInfo {
+	return PatchInfo{
+		Type: WAPatchRegular,
+		Mutations: []MutationInfo{
+			newQuickReplyMutation(id, shortcut, message, keywords, count, false, associatedLabelIDs),
+		},
+	}
+}
+
+// BuildQuickReplyDelete builds an app state tombstone for deleting a quick reply.
+func BuildQuickReplyDelete(id string) PatchInfo {
+	return PatchInfo{
+		Type: WAPatchRegular,
+		Mutations: []MutationInfo{
+			newQuickReplyMutation(id, "", "", []string{}, 0, true, nil),
+		},
+	}
+}
+
 func newSettingPushNameMutation(pushName string) MutationInfo {
 	return MutationInfo{
 		Index:   []string{IndexSettingPushName},

appstate/encode_label_test.go

@@ -0,0 +1,45 @@
+package appstate
+
+import (
+	"testing"
+
+	"github.com/polymorfa/hypermeow/types"
+)
+
+func TestBuildLabelChatChangesUsesOnePatch(t *testing.T) {
+	target := types.NewJID("15551234567", types.DefaultUserServer)
+	patch := BuildLabelChatChanges(target, []LabelChatChange{
+		{LabelID: "1", Labeled: false},
+		{LabelID: "2", Labeled: true},
+	})
+	if patch.Type != WAPatchRegular || len(patch.Mutations) != 2 {
+		t.Fatalf("patch = %#v", patch)
+	}
+	for index, want := range []struct {
+		labelID string
+		labeled bool
+	}{{"1", false}, {"2", true}} {
+		mutation := patch.Mutations[index]
+		if mutation.Version != 3 || len(mutation.Index) != 3 || mutation.Index[1] != want.labelID || mutation.Index[2] != target.String() {
+			t.Fatalf("mutation %d = %#v", index, mutation)
+		}
+		if mutation.Value.GetLabelAssociationAction().GetLabeled() != want.labeled {
+			t.Fatalf("mutation %d labeled = %v", index, mutation.Value.GetLabelAssociationAction().GetLabeled())
+		}
+	}
+}
+
+func TestBuildLabelChatChangesDeduplicatesLabelIDs(t *testing.T) {
+	target := types.NewJID("15551234567", types.DefaultUserServer)
+	patch := BuildLabelChatChanges(target, []LabelChatChange{
+		{LabelID: "1", Labeled: false},
+		{LabelID: "2", Labeled: true},
+		{LabelID: "1", Labeled: true},
+	})
+	if len(patch.Mutations) != 2 {
+		t.Fatalf("mutation count = %d, want 2", len(patch.Mutations))
+	}
+	if patch.Mutations[0].Index[1] != "1" || !patch.Mutations[0].Value.GetLabelAssociationAction().GetLabeled() {
+		t.Fatalf("duplicate label did not preserve its final state: %#v", patch.Mutations[0])
+	}
+}