CommunitySupportController

struct CommunitySupportController : APIRouteCollection

The collection of /api/v3/communitysupport/* route endpoints and handler functions for Community Support reports.

Community Support team members (holders of UserRoleType.communitysupport) file reports about things attendees tell them. Anyone on the team, and TwitarrTeam and above (which includes THO and admin), can file and read the reports, change their status, and start or open a discussion thread about one in the private Community Support forum category. Plain moderators have no access to the reports. Everything is recorded in an append-only log.

Important

allowedRoles and minAccess are OR’d by MinUserAccessLevelMiddleware, and minAccess defaults to .banned–so a role-only route that omits minAccess would admit every logged-in user. Every route here sets minAccess explicitly.

Show on GitHub

registerRoutes(_:)
Required. Registers routes to the incoming router.
Declaration
Swift

func registerRoutes(_ app: Application) throws
Show on GitHub

Access

guardCanAccess(_:)
Throws 403 unless the user is on the Community Support team, or is TwitarrTeam or above. The route middleware already checks this; the in-handler check keeps a route that’s mistakenly registered without the right group from becoming open.
Declaration
Swift

private func guardCanAccess(_ user: UserCacheData) throws
Show on GitHub

Handlers


                    
                    
                    createReportHandler(_:)

Asynchronous

POST /api/v3/communitysupport/report

Files a Community Support report.

Throws

403 if the user isn’t on the Community Support team or TwitarrTeam and above.

Declaration

Swift

func createReportHandler(_ req: Request) async throws -> Response

Parameters


                                requestBody

CommunitySupportReportCreateData

Return Value

201 Created with a CommunitySupportReportData.

Show on GitHub

reportsHandler(_:) Asynchronous
GET /api/v3/communitysupport/reports

The report queue, newest first.

URL Query Parameters:
- status=STRING Only reports with this status: new, inProgress, resolved, or infoOnly. May be given more than once.
- start=INT, limit=INT Pagination.
Declaration
Swift

func reportsHandler(_ req: Request) async throws -> Paginated<CommunitySupportReportListData>
Return Value

Paginated<CommunitySupportReportListData>

Show on GitHub
reportHandler(_:) Asynchronous
GET /api/v3/communitysupport/report/:report_id

One report, with its timeline.
Declaration
Swift

func reportHandler(_ req: Request) async throws -> CommunitySupportReportData
Return Value

CommunitySupportReportData

Show on GitHub


                    
                    
                    statusHandler(_:)

Asynchronous

POST /api/v3/communitysupport/report/:report_id/status

Changes a report’s status, optionally with a note saying why.

Throws

400 if the status is unknown or is already the report’s status.

Declaration

Swift

func statusHandler(_ req: Request) async throws -> CommunitySupportReportData

Parameters


                                requestBody

CommunitySupportStatusChangeData

Return Value

The updated CommunitySupportReportData.

Show on GitHub

discussionHandler(_:) Asynchronous
POST /api/v3/communitysupport/report/:report_id/discussion

Starts a discussion thread about the report in the private Community Support forum category, or–if one already exists–returns it. The first post of a new thread is a full copy of the report (cut down to fit the forum’s post length limit), and the thread’s ID is recorded on the report. Two people asking at the same moment get the same thread.
Declaration
Swift

func discussionHandler(_ req: Request) async throws -> CommunitySupportDiscussionData
Return Value

CommunitySupportDiscussionData

Show on GitHub
discussionLock
Serializes discussionHandler per report.
Declaration
Swift

static let discussionLock: KeyedAsyncLock
Show on GitHub
findOrCreateDiscussion(reportID:cacheUser:on:) Asynchronous
The body of discussionHandler. Callers must hold discussionLock for the report.
Declaration
Swift

private func findOrCreateDiscussion(reportID: UUID, cacheUser: UserCacheData, on req: Request) async throws -> CommunitySupportDiscussionData
Show on GitHub
actionLogHandler(_:) Asynchronous
GET /api/v3/communitysupport/actionlog

The team-wide audit log: everything done to any report, newest first.

URL Query Parameters:
- start=INT, limit=INT Pagination.
Declaration
Swift

func actionLogHandler(_ req: Request) async throws -> Paginated<CommunitySupportActionData>
Return Value

Paginated<CommunitySupportActionData>

Show on GitHub
exportHandler(_:) Asynchronous
GET /api/v3/communitysupport/export

Every Community Support report, oldest first, for a CSV download. THO and above only. Each export is recorded in the action log. The returned reports’ actions arrays are empty; use GET /report/:report_id for a report’s timeline.
Declaration
Swift

func exportHandler(_ req: Request) async throws -> [CommunitySupportReportData]
Return Value

[CommunitySupportReportData]

Show on GitHub

Utilities

buildReportData(_:on:) Asynchronous
Builds the full report DTO: the report, its timeline oldest first, and its discussion thread if that still exists.
Declaration
Swift

func buildReportData(_ report: CommunitySupportReport, on req: Request) async throws -> CommunitySupportReportData
Show on GitHub
liveForumIDs(for:on:) Asynchronous
Of the discussion threads the given reports point at, the IDs of the ones that haven’t been deleted. A soft-deleted forum leaves its ID on the report, so the stored ID alone can’t be trusted.
Declaration
Swift

func liveForumIDs(for reports: [CommunitySupportReport], on db: Database) async throws -> Set<UUID>
Show on GitHub
guardUserExists(_:on:) Asynchronous
Throws 400 if a user ID is given but no such user exists.
Declaration
Swift

private func guardUserExists(_ userID: UUID?, on req: Request) async throws
Show on GitHub