mirrors/gotosocial
1
0
Fork 0
mirror of https://github.com/superseriousbusiness/gotosocial.git synced 2025-12-30 04:16:14 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'main' into xvello/import-mutes

Browse source
This commit is contained in:
Xavier Vello 2025-01-27 17:29:59 +01:00 • committed by GitHub
commit f30ab4bae4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
328 changed files with 31571 additions and 115701 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/api/ratelimiting.md
View file

@ -24,11 +24,11 @@ In case the rate limit is exceeded, an [HTTP 429 Too Many Requests](https://deve
### My rate limit keeps being exceeded! Why?
If you find that your rate limit is regularly being exceeded (both for yourself and other callers) during normal use of your instance, it may be that GoToSocial can't tell the clients apart by IP address. You can investigate this by viewing the logs of your instance. If (almost) all logged IP addresses appear to be the same IP address (something like `172.x.x.x`), then the rate limiting will cause problems.
If you find that your rate limit is regularly being exceeded (both for yourself and other callers) during normal use of your instance, it may be that GoToSocial can't tell the clients apart by IP address. You can investigate this by viewing the logs of your instance. If (almost) all logged client IP addresses appear to be the same IP address (something like `172.x.x.x`), then the rate limiting will cause problems.
This happens when your server is running inside NAT (port forwarding), or behind an HTTP proxy without the correct configuration, causing your instance to see all incoming IP addresses as the same address: namely, the IP address of your reverse proxy or gateway. This means that all incoming requests are *sharing the same rate limit*, rather than being split correctly per IP.
If you are using an HTTP proxy then it's likely that your `trusted-proxies` is not correctly configured. If this is the case, try adding the IP address of your reverse proxy to the list of `trusted-proxies`, and restarting your instance.
If you are using an HTTP proxy then it's likely that your `trusted-proxies` is not correctly configured. See the [trusted-proxies](../configuration/trusted_proxies.md) documentation for more info on how to resolve this.
If you don't have an HTTP proxy, then it's likely caused by NAT. In this case you should disable rate limiting altogether.

450
docs/api/swagger.yaml
View file

@ -186,6 +186,10 @@ definitions:
title: TimelineMarker contains information about a user's progress through a specific timeline.
type: object
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
WebPushNotificationPolicy:
title: WebPushNotificationPolicy names sets of accounts that can generate notifications.
type: string
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
account:
description: The modelled account can be either a remote account, or one on this instance.
properties:
@ -1946,6 +1950,8 @@ definitions:
$ref: '#/definitions/instanceV2ConfigurationTranslation'
urls:
$ref: '#/definitions/instanceV2URLs'
vapid:
$ref: '#/definitions/instanceV2ConfigurationVAPID'
title: Configured values and limits for this instance.
type: object
x-go-name: InstanceV2Configuration
@ -1962,6 +1968,16 @@ definitions:
type: object
x-go-name: InstanceV2ConfigurationTranslation
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
instanceV2ConfigurationVAPID:
properties:
public_key:
description: The instance's VAPID public key, Base64-encoded.
type: string
x-go-name: PublicKey
title: InstanceV2ConfigurationVAPID holds the instance's VAPID configuration.
type: object
x-go-name: InstanceV2ConfigurationVAPID
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
instanceV2Contact:
properties:
account:
@ -3381,6 +3397,139 @@ definitions:
type: object
x-go-name: User
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
webPushNotification:
description: |-
It does not contain an entire Notification, just the NotificationID and some preview information.
It is not used in the client API directly, but is included in the API doc for decoding Web Push notifications.
properties:
access_token:
description: |-
AccessToken is the access token associated with the Web Push subscription.
I don't know why this is sent, given that the client should know that already,
but Feditext does use it.
type: string
x-go-name: AccessToken
body:
description: |-
Body is a preview of the notification body,
such as the first line of a status's CW or text,
or the first line of an account bio.
type: string
x-go-name: Body
icon:
description: |-
Icon is an image URL that can be displayed with the notification,
normally the account's avatar.
type: string
x-go-name: Icon
notification_id:
description: NotificationID is the Notification.ID of the referenced Notification.
type: string
x-go-name: NotificationID
notification_type:
description: NotificationType is the Notification.Type of the referenced Notification.
type: string
x-go-name: NotificationType
preferred_locale:
description: PreferredLocale is a BCP 47 language tag for the receiving user's locale.
type: string
x-go-name: PreferredLocale
title:
description: |-
Title is a title for the notification,
generally describing an action taken by a user.
type: string
x-go-name: Title
title: WebPushNotification represents a notification summary delivered to the client by the Web Push server.
type: object
x-go-name: WebPushNotification
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
webPushSubscription:
properties:
alerts:
$ref: '#/definitions/webPushSubscriptionAlerts'
endpoint:
description: Where push alerts will be sent to.
type: string
x-go-name: Endpoint
id:
description: The id of the push subscription in the database.
type: string
x-go-name: ID
policy:
$ref: '#/definitions/WebPushNotificationPolicy'
server_key:
description: The streaming server's VAPID public key.
type: string
x-go-name: ServerKey
standard:
description: |-
Whether the subscription uses RFC or pre-RFC Web Push standards.
For GotoSocial, this is always true.
type: boolean
x-go-name: Standard
title: WebPushSubscription represents a subscription to a Web Push server.
type: object
x-go-name: WebPushSubscription
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
webPushSubscriptionAlerts:
properties:
admin.report:
description: Receive a push notification when a new report has been filed?
type: boolean
x-go-name: AdminReport
admin.sign_up:
description: Receive a push notification when a new user has signed up?
type: boolean
x-go-name: AdminSignup
favourite:
description: Receive a push notification when a status you created has been favourited by someone else?
type: boolean
x-go-name: Favourite
follow:
description: Receive a push notification when someone has followed you?
type: boolean
x-go-name: Follow
follow_request:
description: Receive a push notification when someone has requested to follow you?
type: boolean
x-go-name: FollowRequest
mention:
description: Receive a push notification when someone else has mentioned you in a status?
type: boolean
x-go-name: Mention
pending.favourite:
description: Receive a push notification when a fave is pending?
type: boolean
x-go-name: PendingFavourite
pending.reblog:
description: Receive a push notification when a boost is pending?
type: boolean
x-go-name: PendingReblog
pending.reply:
description: Receive a push notification when a reply is pending?
type: boolean
x-go-name: PendingReply
poll:
description: Receive a push notification when a poll you voted in or created has ended?
type: boolean
x-go-name: Poll
reblog:
description: Receive a push notification when a status you created has been boosted by someone else?
type: boolean
x-go-name: Reblog
status:
description: Receive a push notification when a subscribed account posts a status?
type: boolean
x-go-name: Status
update:
description: Receive a push notification when a status you interacted with has been edited?
type: boolean
x-go-name: Update
title: WebPushSubscriptionAlerts represents the specific events that this Web Push subscription will receive.
type: object
x-go-name: WebPushSubscriptionAlerts
x-go-package: github.com/superseriousbusiness/gotosocial/internal/api/model
wellKnownResponse:
description: See https://webfinger.net/
properties:
@ -7805,14 +7954,14 @@ paths:
The contexts in which the filter should be applied.
Sample: home, public
enum:
- home
- notifications
- public
- thread
- account
in: formData
items:
enum:
- home
- notifications
- public
- thread
- account
type: string
minItems: 1
name: context[]
@ -7959,14 +8108,14 @@ paths:
The contexts in which the filter should be applied.
Sample: home, public
enum:
- home
- notifications
- public
- thread
- account
in: formData
items:
enum:
- home
- notifications
- public
- thread
- account
type: string
minItems: 1
name: context[]
@ -9642,6 +9791,259 @@ paths:
summary: Delete the authenticated account's header.
tags:
- accounts
/api/v1/push/subscription:
delete:
description: If there is no subscription, returns successfully anyway.
operationId: pushSubscriptionDelete
responses:
"200":
description: Push subscription deleted, or did not exist.
"400":
description: bad request
"401":
description: unauthorized
"500":
description: internal server error
security:
- OAuth2 Bearer:
- push
summary: Delete the Web Push subscription associated with the current auth token.
tags:
- push
get:
operationId: pushSubscriptionGet
produces:
- application/json
responses:
"200":
description: Web Push subscription for current access token.
schema:
$ref: '#/definitions/webPushSubscription'
"400":
description: bad request
"401":
description: unauthorized
"404":
description: This access token doesn't have an associated subscription.
"500":
description: internal server error
security:
- OAuth2 Bearer:
- push
summary: Get the push subscription for the current access token.
tags:
- push
post:
consumes:
- application/json
- application/x-www-form-urlencoded
operationId: pushSubscriptionPost
parameters:
- description: The URL to which Web Push notifications will be sent.
in: formData
minLength: 1
name: subscription[endpoint]
required: true
type: string
- description: The auth secret, a Base64 encoded string of 16 bytes of random data.
in: formData
minLength: 1
name: subscription[keys][auth]
required: true
type: string
- description: The user agent public key, a Base64 encoded string of a public key from an ECDH keypair using the prime256v1 curve.
in: formData
minLength: 1
name: subscription[keys][p256dh]
required: true
type: string
- default: false
description: Receive a push notification when someone has followed you?
in: formData
name: data[alerts][follow]
type: boolean
- default: false
description: Receive a push notification when someone has requested to follow you?
in: formData
name: data[alerts][follow_request]
type: boolean
- default: false
description: Receive a push notification when a status you created has been favourited by someone else?
in: formData
name: data[alerts][favourite]
type: boolean
- default: false
description: Receive a push notification when someone else has mentioned you in a status?
in: formData
name: data[alerts][mention]
type: boolean
- default: false
description: Receive a push notification when a status you created has been boosted by someone else?
in: formData
name: data[alerts][reblog]
type: boolean
- default: false
description: Receive a push notification when a poll you voted in or created has ended?
in: formData
name: data[alerts][poll]
type: boolean
- default: false
description: Receive a push notification when a subscribed account posts a status?
in: formData
name: data[alerts][status]
type: boolean
- default: false
description: Receive a push notification when a status you interacted with has been edited?
in: formData
name: data[alerts][update]
type: boolean
- default: false
description: Receive a push notification when a new user has signed up?
in: formData
name: data[alerts][admin.sign_up]
type: boolean
- default: false
description: Receive a push notification when a new report has been filed?
in: formData
name: data[alerts][admin.report]
type: boolean
- default: false
description: Receive a push notification when a fave is pending?
in: formData
name: data[alerts][pending.favourite]
type: boolean
- default: false
description: Receive a push notification when a reply is pending?
in: formData
name: data[alerts][pending.reply]
type: boolean
- default: false
description: Receive a push notification when a boost is pending?
in: formData
name: data[alerts][pending.reblog]
type: boolean
produces:
- application/json
responses:
"200":
description: Web Push subscription for current access token.
schema:
$ref: '#/definitions/webPushSubscription'
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"404":
description: not found
"406":
description: not acceptable
"500":
description: internal server error
security:
- OAuth2 Bearer:
- push
summary: Create a new Web Push subscription for the current access token, or replace the existing one.
tags:
- push
put:
consumes:
- application/json
- application/x-www-form-urlencoded
description: Only which notifications you receive can be updated.
operationId: pushSubscriptionPut
parameters:
- default: false
description: Receive a push notification when someone has followed you?
in: formData
name: data[alerts][follow]
type: boolean
- default: false
description: Receive a push notification when someone has requested to follow you?
in: formData
name: data[alerts][follow_request]
type: boolean
- default: false
description: Receive a push notification when a status you created has been favourited by someone else?
in: formData
name: data[alerts][favourite]
type: boolean
- default: false
description: Receive a push notification when someone else has mentioned you in a status?
in: formData
name: data[alerts][mention]
type: boolean
- default: false
description: Receive a push notification when a status you created has been boosted by someone else?
in: formData
name: data[alerts][reblog]
type: boolean
- default: false
description: Receive a push notification when a poll you voted in or created has ended?
in: formData
name: data[alerts][poll]
type: boolean
- default: false
description: Receive a push notification when a subscribed account posts a status?
in: formData
name: data[alerts][status]
type: boolean
- default: false
description: Receive a push notification when a status you interacted with has been edited?
in: formData
name: data[alerts][update]
type: boolean
- default: false
description: Receive a push notification when a new user has signed up?
in: formData
name: data[alerts][admin.sign_up]
type: boolean
- default: false
description: Receive a push notification when a new report has been filed?
in: formData
name: data[alerts][admin.report]
type: boolean
- default: false
description: Receive a push notification when a fave is pending?
in: formData
name: data[alerts][pending.favourite]
type: boolean
- default: false
description: Receive a push notification when a reply is pending?
in: formData
name: data[alerts][pending.reply]
type: boolean
- default: false
description: Receive a push notification when a boost is pending?
in: formData
name: data[alerts][pending.reblog]
type: boolean
produces:
- application/json
responses:
"200":
description: Web Push subscription for current access token.
schema:
$ref: '#/definitions/webPushSubscription'
"400":
description: bad request
"401":
description: unauthorized
"403":
description: forbidden
"404":
description: This access token doesn't have an associated subscription.
"406":
description: not acceptable
"500":
description: internal server error
security:
- OAuth2 Bearer:
- push
summary: Update the Web Push subscription for the current access token.
tags:
- push
/api/v1/reports:
get:
description: |-
@ -11433,14 +11835,14 @@ paths:
The contexts in which the filter should be applied.
Sample: home, public
enum:
- home
- notifications
- public
- thread
- account
in: formData
items:
enum:
- home
- notifications
- public
- thread
- account
type: string
minItems: 1
name: context[]
@ -11627,14 +12029,14 @@ paths:
The contexts in which the filter should be applied.
Sample: home, public
enum:
- home
- notifications
- public
- thread
- account
in: formData
items:
enum:
- home
- notifications
- public
- thread
- account
type: string
minItems: 1
name: context[]

4
docs/configuration/general.md
View file

@ -1,8 +1,6 @@
# General
The top-level configuration for GoToSocial, including basic things like host, port, bind address and transport protocol.
The only things you *really* need to set here are `host`, which should be the hostname where your instance is reachable, and probably `port`.
The top-level configuration for GoToSocial, including basic things like host, port, bind address, and trusted-proxies.
## Settings

79
docs/configuration/trusted_proxies.md Normal file
View file

@ -0,0 +1,79 @@
# Trusted Proxies
To correctly enforce [rate limiting](../api/ratelimiting.md), GoToSocial relies on the concept of "trusted proxies" in order to accurately determine the IP address of clients accessing your server.
A "trusted proxy" is an intermediate network hop that GoToSocial can be instructed to trust to provide a correct client IP address.
For example, if you are running in a reverse proxy configuration with Docker + Nginx, then the Docker network address of Nginx should be configured as a trusted proxy, since all traffic from the wider internet will come into GoToSocial via Nginx.
Without setting `trusted-proxies` correctly, GoToSocial will see all incoming client IP addresses as the same address, which leads to rate limiting issues, since GoToSocial uses client IP addresses to bucket rate limits.
## tl;dr: How to set `trusted-proxies` correctly
If your `trusted-proxies` setting is not correctly configured, you may see the following warning on the web view of your instance (v0.18.0 and above):
> Warning! It looks like trusted-proxies is not set correctly in this instance's configuration. This may cause rate-limiting issues and, by extension, federation issues.
>
> If you are the instance admin, you should fix this by adding `SUGGESTED_IP_RANGE` to your trusted-proxies.
To resolve this, copy the IP range in the message, and edit your `config.yaml` file to add the IP range to your `trusted-proxies`.
!!! tip "You may be getting rate limited even if you don't see the above warning!"
If you're on a version of GoToSocial below v0.18.0, or you're running behind a CDN such as Cloudflare (not recommended), you won't see a warning message. Instead, you'll see in your GoToSocial logs that all client IPs are the same address. In this case, take the recurring client IP value as `SUGGESTED_IP_RANGE`.
In this example, we assume `SUGGESTED_IP_RANGE` to be `172.17.0.1/16` (the default Docker bridge network subnet).
Before (default config):
```yaml
trusted-proxies:
- "127.0.0.1/32"
- "::1"
```
After (new config):
```yaml
trusted-proxies:
- "172.17.0.1/16"
- "127.0.0.1/32"
- "::1"
```
If you are using [environment variables](../configuration/index.md#environment-variables) to configure your instance, you can configure `trusted-proxies` by setting the environment variable `GTS_TRUSTED_PROXIES` to a comma-separated list of IP ranges, like so:
```env
GTS_TRUSTED_PROXIES="172.17.0.1/16,127.0.0.1/32,::1"
```
If you are using docker compose, your docker-compose.yaml file should look something like this after the change (note that yaml uses `: ` and not `=`):
```yaml
################################
# BLAH BLAH OTHER CONFIG STUFF #
################################
environment:
############################
# BLAH BLAH OTHER ENV VARS #
############################
## For reverse proxy setups:
GTS_TRUSTED_PROXIES: "172.17.0.1/16,127.0.0.1/32,::1"
################################
# BLAH BLAH OTHER CONFIG STUFF #
################################
```
Once you have made the necessary configuration changes, **restart your instance** and refresh the home page.
If the message is gone, then the problem is resolved!
If you still see the warning message but with a different suggested IP range to add to `trusted-proxies`, then follow the same steps as above again, including the new suggested IP range in your config in addition to the one you just added.
!!! tip "Cloudflare IP Addresses"
If you are running with a CDN/proxy such as Cloudflare in front of your GoToSocial instance (not recommended), then you may need to add one or more of the Cloudflare IP addresses to your `trusted-proxies` in order to have rate limiting work properly. You can find a list of Cloudflare IP addresses here: https://www.cloudflare.com/ips/
## I can't seem to get `trusted-proxies` configured properly, can I just disable the warning?
There are some situations where it's not practically possible to get `trusted-proxies` configured correctly to detect the real client IP of incoming requests For example, if you're running GoToSocial behind a home internet router that cannot inject an `X-Forwarded-For` header, then your suggested entry to add to `trusted-proxies` will look something like `192.168.x.x`, but adding this to `trusted-proxies` won't resolve the issue.
If you've tried everything, then you can disable the warning message by just turning off rate limiting entirely, ie., by setting `advanced-rate-limit-requests` to 0 in your config.yaml, or setting the environment variable `GTS_ADVANCED_RATE_LIMIT_REQUESTS` to 0. Don't forget to **restart your instance** after changing this setting.

8
docs/federation/actors.md
View file

@ -1,5 +1,13 @@
# Actors and Actor Properties
## `Service` vs `Person` actors
GoToSocial serves most accounts as the ActivityStreams `Person` type described [here](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-person).
Accounts that users have selected to mark as bot accounts, however, will use the `Service` type described [here](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-service).
This type distinction can be used by remote servers to distinguish between bot accounts and "regular" user accounts.
## Inbox
GoToSocial implements Inboxes for Actors following the ActivityPub specification [here](https://www.w3.org/TR/activitypub/#inbox).

4
docs/getting_started/reverse_proxy/index.md
View file

@ -41,3 +41,7 @@ We have guides available for the following servers:
When using a reverse-proxy, special care must be taken to allow WebSockets to work too. This is necessary as many client applications use WebSockets to stream your timeline. WebSockets is not used as part of federation.
Make sure you read the [WebSocket](websocket.md) documentation and configure your reverse proxy accordingly.
## Trusted Proxies
When using a reverse-proxy, you may run into issues with rate limiting and `trusted-proxies`. Check the [trusted proxies](../../configuration/trusted_proxies.md) documentation if you have any problems.