[feature] Implement markers API (#1989)

* Implement markers API

Fixes #1856

* Correct import grouping in markers files

* Regenerate Swagger for markers API

* Shorten names for readability

* Cache markers for 6 hours

* Update DB ref

* Update envparsing.sh

7 files changed, 348 insertions, 0 deletions

diff --git a/internal/db/bundb/bundb.go b/internal/db/bundb/bundb.go
index 5634f877f..6a6ff2224 100644
--- a/internal/db/bundb/bundb.go
+++ b/internal/db/bundb/bundb.go
@@ -66,6 +66,7 @@ type DBService struct {
 	db.Emoji
 	db.Instance
 	db.List
+	db.Marker
 	db.Media
 	db.Mention
 	db.Notification
@@ -186,6 +187,10 @@ func NewBunDBService(ctx context.Context, state *state.State) (db.DB, error) {
 			db:    db,
 			state: state,
 		},
+		Marker: &markerDB{
+			db:    db,
+			state: state,
+		},
 		Media: &mediaDB{
 			db:    db,
 			state: state,
diff --git a/internal/db/bundb/bundb_test.go b/internal/db/bundb/bundb_test.go
index d54578795..d608f7bc4 100644
--- a/internal/db/bundb/bundb_test.go
+++ b/internal/db/bundb/bundb_test.go
@@ -50,6 +50,7 @@ type BunDBStandardTestSuite struct {
 	testLists        map[string]*gtsmodel.List
 	testListEntries  map[string]*gtsmodel.ListEntry
 	testAccountNotes map[string]*gtsmodel.AccountNote
+	testMarkers      map[string]*gtsmodel.Marker
 }
 
 func (suite *BunDBStandardTestSuite) SetupSuite() {
@@ -70,6 +71,7 @@ func (suite *BunDBStandardTestSuite) SetupSuite() {
 	suite.testLists = testrig.NewTestLists()
 	suite.testListEntries = testrig.NewTestListEntries()
 	suite.testAccountNotes = testrig.NewTestAccountNotes()
+	suite.testMarkers = testrig.NewTestMarkers()
 }
 
 func (suite *BunDBStandardTestSuite) SetupTest() {
diff --git a/internal/db/bundb/marker.go b/internal/db/bundb/marker.go
new file mode 100644
index 000000000..12526e659
--- /dev/null
+++ b/internal/db/bundb/marker.go
@@ -0,0 +1,115 @@
+// GoToSocial
+// Copyright (C) GoToSocial Authors admin@gotosocial.org
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+package bundb
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/superseriousbusiness/gotosocial/internal/db"
+	"github.com/superseriousbusiness/gotosocial/internal/gtsmodel"
+	"github.com/superseriousbusiness/gotosocial/internal/state"
+	"github.com/uptrace/bun"
+)
+
+type markerDB struct {
+	db    *WrappedDB
+	state *state.State
+}
+
+/*
+	MARKER FUNCTIONS
+*/
+
+func (m *markerDB) GetMarker(ctx context.Context, accountID string, name gtsmodel.MarkerName) (*gtsmodel.Marker, error) {
+	marker, err := m.state.Caches.GTS.Marker().Load(
+		"AccountID.Name",
+		func() (*gtsmodel.Marker, error) {
+			var marker gtsmodel.Marker
+
+			if err := m.db.NewSelect().
+				Model(&marker).
+				Where("? = ? AND ? = ?", bun.Ident("account_id"), accountID, bun.Ident("name"), name).
+				Scan(ctx); err != nil {
+				return nil, m.db.ProcessError(err)
+			}
+
+			return &marker, nil
+		},
+		accountID,
+		name,
+	)
+	if err != nil {
+		return nil, err // already processed
+	}
+
+	return marker, nil
+}
+
+func (m *markerDB) UpdateMarker(ctx context.Context, marker *gtsmodel.Marker) error {
+	prevMarker, err := m.GetMarker(ctx, marker.AccountID, marker.Name)
+	if err != nil && !errors.Is(err, db.ErrNoEntries) {
+		return fmt.Errorf("UpdateMarker: error fetching previous version of marker: %w", err)
+	}
+
+	marker.UpdatedAt = time.Now()
+	if prevMarker != nil {
+		marker.Version = prevMarker.Version + 1
+	}
+
+	return m.state.Caches.GTS.Marker().Store(marker, func() error {
+		if prevMarker == nil {
+			if _, err := m.db.NewInsert().
+				Model(marker).
+				Exec(ctx); err != nil {
+				return m.db.ProcessError(err)
+			}
+			return nil
+		}
+
+		// Optimistic concurrency control: start a transaction, try to update a row with a previously retrieved version.
+		// If the update in the transaction fails to actually change anything, another update happened concurrently, and
+		// this update should be retried by the caller, which in this case involves sending HTTP 409 to the API client.
+		return m.db.RunInTx(ctx, func(tx bun.Tx) error {
+			result, err := tx.NewUpdate().
+				Model(marker).
+				WherePK().
+				Where("? = ?", bun.Ident("version"), prevMarker.Version).
+				Exec(ctx)
+			if err != nil {
+				return m.db.ProcessError(err)
+			}
+
+			rowsAffected, err := result.RowsAffected()
+			if err != nil {
+				return m.db.ProcessError(err)
+			}
+			if rowsAffected == 0 {
+				// Will trigger a rollback, although there should be no changes to roll back.
+				return db.ErrAlreadyExists
+			} else if rowsAffected > 1 {
+				// This shouldn't happen.
+				return db.ErrNoEntries
+			}
+
+			return nil
+		})
+	})
+}
diff --git a/internal/db/bundb/markers_test.go b/internal/db/bundb/markers_test.go
new file mode 100644
index 000000000..eb0a43437
--- /dev/null
+++ b/internal/db/bundb/markers_test.go
@@ -0,0 +1,127 @@
+// GoToSocial
+// Copyright (C) GoToSocial Authors admin@gotosocial.org
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <http:www.gnu.org/licenses/>.
+
+package bundb_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/suite"
+	"github.com/superseriousbusiness/gotosocial/internal/db"
+	"github.com/superseriousbusiness/gotosocial/internal/gtsmodel"
+)
+
+// MarkersTestSuite uses home timelines for Get tests
+// and notifications timelines for Update tests
+// so that multiple tests running at once can't step on each other.
+type MarkersTestSuite struct {
+	BunDBStandardTestSuite
+}
+
+func (suite *MarkersTestSuite) TestGetExisting() {
+	ctx := context.Background()
+
+	// This account has home and notifications markers set.
+	localAccount1 := suite.testAccounts["local_account_1"]
+	marker, err := suite.db.GetMarker(ctx, localAccount1.ID, gtsmodel.MarkerNameHome)
+	suite.NoError(err)
+	if err != nil {
+		suite.FailNow(err.Error())
+	}
+	// Should match our fixture.
+	suite.Equal("01F8MH82FYRXD2RC6108DAJ5HB", marker.LastReadID)
+}
+
+func (suite *MarkersTestSuite) TestGetUnset() {
+	ctx := context.Background()
+
+	// This account has no markers set.
+	localAccount2 := suite.testAccounts["local_account_2"]
+	marker, err := suite.db.GetMarker(ctx, localAccount2.ID, gtsmodel.MarkerNameHome)
+	// Should not return anything.
+	suite.Nil(marker)
+	suite.ErrorIs(err, db.ErrNoEntries)
+}
+
+func (suite *MarkersTestSuite) TestUpdateExisting() {
+	ctx := context.Background()
+
+	now := time.Now()
+	// This account has home and notifications markers set.
+	localAccount1 := suite.testAccounts["local_account_1"]
+	prevMarker := suite.testMarkers["local_account_1_notification_marker"]
+	marker := &gtsmodel.Marker{
+		AccountID:  localAccount1.ID,
+		Name:       gtsmodel.MarkerNameNotifications,
+		LastReadID: "01H57YZECGJ2ZW39H8TJWAH0KY",
+	}
+	err := suite.db.UpdateMarker(ctx, marker)
+	suite.NoError(err)
+	if err != nil {
+		suite.FailNow(err.Error())
+	}
+	// Modifies the update and version fields of the marker as an intentional side effect.
+	suite.GreaterOrEqual(marker.UpdatedAt, now)
+	suite.Greater(marker.Version, prevMarker.Version)
+
+	// Re-fetch it from the DB and confirm that we got the updated version.
+	marker2, err := suite.db.GetMarker(ctx, localAccount1.ID, gtsmodel.MarkerNameNotifications)
+	suite.NoError(err)
+	if err != nil {
+		suite.FailNow(err.Error())
+	}
+	suite.GreaterOrEqual(marker2.UpdatedAt, now)
+	suite.GreaterOrEqual(marker2.Version, prevMarker.Version)
+	suite.Equal("01H57YZECGJ2ZW39H8TJWAH0KY", marker2.LastReadID)
+}
+
+func (suite *MarkersTestSuite) TestUpdateUnset() {
+	ctx := context.Background()
+
+	now := time.Now()
+	// This account has no markers set.
+	localAccount2 := suite.testAccounts["local_account_2"]
+	marker := &gtsmodel.Marker{
+		AccountID:  localAccount2.ID,
+		Name:       gtsmodel.MarkerNameNotifications,
+		LastReadID: "01H57ZVGMD348ZJD5WENDZDH9Z",
+	}
+	err := suite.db.UpdateMarker(ctx, marker)
+	suite.NoError(err)
+	if err != nil {
+		suite.FailNow(err.Error())
+	}
+	// Modifies the update and version fields of the marker as an intentional side effect.
+	suite.GreaterOrEqual(marker.UpdatedAt, now)
+	suite.GreaterOrEqual(marker.Version, 0)
+
+	// Re-fetch it from the DB and confirm that we got the updated version.
+	marker2, err := suite.db.GetMarker(ctx, localAccount2.ID, gtsmodel.MarkerNameNotifications)
+	suite.NoError(err)
+	if err != nil {
+		suite.FailNow(err.Error())
+	}
+	suite.GreaterOrEqual(marker2.UpdatedAt, now)
+	suite.GreaterOrEqual(marker2.Version, 0)
+	suite.Equal("01H57ZVGMD348ZJD5WENDZDH9Z", marker2.LastReadID)
+}
+
+func TestMarkersTestSuite(t *testing.T) {
+	suite.Run(t, new(MarkersTestSuite))
+}
diff --git a/internal/db/bundb/migrations/20230713025939_markers_api.go b/internal/db/bundb/migrations/20230713025939_markers_api.go
new file mode 100644
index 000000000..b2ace6856
--- /dev/null
+++ b/internal/db/bundb/migrations/20230713025939_markers_api.go
@@ -0,0 +1,66 @@
+// GoToSocial
+// Copyright (C) GoToSocial Authors admin@gotosocial.org
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+package migrations
+
+import (
+	"context"
+
+	gtsmodel "github.com/superseriousbusiness/gotosocial/internal/gtsmodel"
+	"github.com/uptrace/bun"
+)
+
+func init() {
+	up := func(ctx context.Context, db *bun.DB) error {
+		return db.RunInTx(ctx, nil, func(ctx context.Context, tx bun.Tx) error {
+			// Marker table.
+			if _, err := tx.
+				NewCreateTable().
+				Model(&gtsmodel.Marker{}).
+				IfNotExists().
+				Exec(ctx); err != nil {
+				return err
+			}
+
+			// Add indexes to the Marker table.
+			for index, columns := range map[string][]string{
+				"markers_account_id_name_idx": {"account_id", "name"},
+			} {
+				if _, err := tx.
+					NewCreateIndex().
+					Table("markers").
+					Index(index).
+					Column(columns...).
+					Exec(ctx); err != nil {
+					return err
+				}
+			}
+
+			return nil
+		})
+	}
+
+	down := func(ctx context.Context, db *bun.DB) error {
+		return db.RunInTx(ctx, nil, func(ctx context.Context, tx bun.Tx) error {
+			return nil
+		})
+	}
+
+	if err := Migrations.Register(up, down); err != nil {
+		panic(err)
+	}
+}
diff --git a/internal/db/db.go b/internal/db/db.go
index f99bd212e..370dab38b 100644
--- a/internal/db/db.go
+++ b/internal/db/db.go
@@ -37,6 +37,7 @@ type DB interface {
 	Emoji
 	Instance
 	List
+	Marker
 	Media
 	Mention
 	Notification
diff --git a/internal/db/marker.go b/internal/db/marker.go
new file mode 100644
index 000000000..14502865b
--- /dev/null
+++ b/internal/db/marker.go
@@ -0,0 +1,32 @@
+// GoToSocial
+// Copyright (C) GoToSocial Authors admin@gotosocial.org
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+package db
+
+import (
+	"context"
+
+	"github.com/superseriousbusiness/gotosocial/internal/gtsmodel"
+)
+
+type Marker interface {
+	// GetMarker gets one marker with the given timeline name.
+	GetMarker(ctx context.Context, accountID string, name gtsmodel.MarkerName) (*gtsmodel.Marker, error)
+
+	// UpdateMarker updates the given marker.
+	UpdateMarker(ctx context.Context, marker *gtsmodel.Marker) error
+}