feature: filters v2 server-side warning/hiding (#2793)

* Remove dead code

* Filter statuses when converting to frontend representation

* status.filtered is an array

* Make matching case-insensitive

* Remove TODOs that don't need to be done now

* Add missing filter check for notification

* lint: rename ErrHideStatus

* APIFilterActionToFilterAction not used yet

* swaggerino docseroni

* Address review comments

* Add apimodel.FilterActionNone

---------

Co-authored-by: tobi <31960611+tsmethurst@users.noreply.github.com>
Co-authored-by: tobi <tobi.smethurst@protonmail.com>

3 files changed, 142 insertions, 0 deletions

diff --git a/internal/api/model/filterresult.go b/internal/api/model/filterresult.go
new file mode 100644
index 000000000..942c2124a
--- /dev/null
+++ b/internal/api/model/filterresult.go
@@ -0,0 +1,34 @@
+// 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 model
+
+// FilterResult is returned along with a filtered status to explain why it was filtered.
+//
+// swagger:model filterResult
+//
+// ---
+// tags:
+// - filters
+type FilterResult struct {
+	// The filter that was matched.
+	Filter FilterV2 `json:"filter"`
+	// The keywords within the filter that were matched.
+	KeywordMatches []string `json:"keyword_matches"`
+	// The status IDs within the filter that were matched.
+	StatusMatches []string `json:"status_matches"`
+}
diff --git a/internal/api/model/filterv2.go b/internal/api/model/filterv2.go
new file mode 100644
index 000000000..797c97213
--- /dev/null
+++ b/internal/api/model/filterv2.go
@@ -0,0 +1,106 @@
+// 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 model
+
+// FilterV2 represents a user-defined filter for determining which statuses should not be shown to the user.
+// v2 filters have names and can include multiple phrases and status IDs to filter.
+//
+// swagger:model filterV2
+//
+// ---
+// tags:
+// - filters
+type FilterV2 struct {
+	// The ID of the filter in the database.
+	ID string `json:"id"`
+	// The name of the filter.
+	//
+	// Example: Linux Words
+	Title string `json:"title"`
+	// The contexts in which the filter should be applied.
+	//
+	// Minimum items: 1
+	// Unique: true
+	// Enum:
+	//	- home
+	//	- notifications
+	//	- public
+	//	- thread
+	//	- account
+	// Example: ["home", "public"]
+	Context []FilterContext `json:"context"`
+	// When the filter should no longer be applied. Null if the filter does not expire.
+	//
+	// Example: 2024-02-01T02:57:49Z
+	ExpiresAt *string `json:"expires_at"`
+	// The action to be taken when a status matches this filter.
+	// Enum:
+	//	- warn
+	//	- hide
+	FilterAction FilterAction `json:"filter_action"`
+	// The keywords grouped under this filter.
+	Keywords []FilterKeyword `json:"keywords"`
+	// The statuses grouped under this filter.
+	Statuses []FilterStatus `json:"statuses"`
+}
+
+// FilterAction is the action to apply to statuses matching a filter.
+type FilterAction string
+
+const (
+	// FilterActionNone filters should not exist, except internally, for partially constructed or invalid filters.
+	FilterActionNone FilterAction = ""
+	// FilterActionWarn filters will include this status in API results with a warning.
+	FilterActionWarn FilterAction = "warn"
+	// FilterActionHide filters will remove this status from API results.
+	FilterActionHide FilterAction = "hide"
+)
+
+// FilterKeyword represents text to filter within a v2 filter.
+//
+// swagger:model filterKeyword
+//
+// ---
+// tags:
+// - filters
+type FilterKeyword struct {
+	// The ID of the filter keyword entry in the database.
+	ID string `json:"id"`
+	// The text to be filtered.
+	//
+	// Example: fnord
+	Keyword string `json:"keyword"`
+	// Should the filter consider word boundaries?
+	//
+	// Example: true
+	WholeWord bool `json:"whole_word"`
+}
+
+// FilterStatus represents a single status to filter within a v2 filter.
+//
+// swagger:model filterStatus
+//
+// ---
+// tags:
+// - filters
+type FilterStatus struct {
+	// The ID of the filter status entry in the database.
+	ID string `json:"id"`
+	// The status ID to be filtered.
+	StatusID string `json:"phrase"`
+}
diff --git a/internal/api/model/status.go b/internal/api/model/status.go
index 9543303eb..9098cb59d 100644
--- a/internal/api/model/status.go
+++ b/internal/api/model/status.go
@@ -100,6 +100,8 @@ type Status struct {
 	// so the user may redraft from the source text without the client having to reverse-engineer
 	// the original text from the HTML content.
 	Text string `json:"text,omitempty"`
+	// A list of filters that matched this status and why they matched, if there are any such filters.
+	Filtered []FilterResult `json:"filtered,omitempty"`
 
 	// Additional fields not exposed via JSON
 	// (used only internally for templating etc).