[feature] Handle retractions of domain permission subscription entries (#4261)

# Description

> If this is a code change, please include a summary of what you've coded, and link to the issue(s) it closes/implements.
>
> If this is a documentation change, please briefly describe what you've changed and why.

This pull request adds logic for nicely handling retractions of entries from domain permission subscriptions.

See docs for how this works but basically retracted entries will either be removed (and possibly picked up by a lower-prio subscription), or orphaned (and then possibly adopted), depending on the config of the domain permission subscription.

closes https://codeberg.org/superseriousbusiness/gotosocial/issues/4101

## Checklist

Please put an x inside each checkbox to indicate that you've read and followed it: `[ ]` -> `[x]`

If this is a documentation change, only the first checkbox must be filled (you can delete the others if you want).

- [x] I/we have read the [GoToSocial contribution guidelines](https://codeberg.org/superseriousbusiness/gotosocial/src/branch/main/CONTRIBUTING.md).
- [x] I/we have discussed the proposed changes already, either in an issue on the repository, or in the Matrix chat.
- [x] I/we have not leveraged AI to create the proposed changes.
- [x] I/we have performed a self-review of added code.
- [x] I/we have written code that is legible and maintainable by others.
- [x] I/we have commented the added code, particularly in hard-to-understand areas.
- [x] I/we have made any necessary changes to documentation.
- [x] I/we have added tests that cover new code.
- [ ] I/we have run tests and they pass locally with the changes.
- [x] I/we have run `go fmt ./...` and `golangci-lint run`.

Reviewed-on: https://codeberg.org/superseriousbusiness/gotosocial/pulls/4261
Co-authored-by: tobi <tobi.smethurst@protonmail.com>
Co-committed-by: tobi <tobi.smethurst@protonmail.com>

1 files changed, 15 insertions, 0 deletions

diff --git a/docs/api/swagger.yaml b/docs/api/swagger.yaml
index 062be9d94..924dcffdb 100644
--- a/docs/api/swagger.yaml
+++ b/docs/api/swagger.yaml
@@ -1289,6 +1289,11 @@ definitions:
                 format: uint8
                 type: integer
                 x-go-name: Priority
+            remove_retracted:
+                description: If true, then when a list is processed, if the list does *not* contain entries that it *did* contain previously, ie., retracted entries, then domain permissions corresponding to those entries will be removed. If false, they will just be orphaned instead.
+                example: true
+                type: boolean
+                x-go-name: RemoveRetracted
             successfully_fetched_at:
                 description: Time of the most recent successful fetch (ISO 8601 Datetime).
                 example: "2021-07-30T09:20:25+00:00"
@@ -6751,6 +6756,11 @@ paths:
                   in: formData
                   name: adopt_orphans
                   type: boolean
+                - default: true
+                  description: If true, then when a list is processed, if the list does *not* contain entries that it *did* contain previously, ie., retracted entries, then domain permissions corresponding to those entries will be removed. If false, they will just be orphaned instead.
+                  in: formData
+                  name: remove_retracted
+                  type: boolean
                 - description: URI to call in order to fetch the permissions list.
                   in: formData
                   name: uri
@@ -6830,6 +6840,11 @@ paths:
                   in: formData
                   name: adopt_orphans
                   type: boolean
+                - default: true
+                  description: If true, then when a list is processed, if the list does *not* contain entries that it *did* contain previously, ie., retracted entries, then domain permissions corresponding to those entries will be removed. If false, they will just be orphaned instead.
+                  in: formData
+                  name: remove_retracted
+                  type: boolean
                 - description: MIME content type to use when parsing the permissions list. One of "text/plain", "text/csv", and "application/json".
                   in: formData
                   name: content_type