AdminController

struct AdminController : APIRouteCollection

The collection of /api/v3/admin route endpoints and handler functions related to admin tasks.

All routes in this group should be restricted to users with administrator priviliges. This controller returns data of a privledged nature, and has control endpoints for setting overall server state.

Show on GitHub

  • Required. Registers routes to the incoming router.

    Declaration

    Swift

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

  • POST /api/v3/admin/dailytheme/create

    Creates a new daily theme for a day of the cruise (or some other day). The ‘day’ field is unique, so attempts to create a new record with the same day as an existing record will fail–instead, you probably want to edit the existing DailyTheme for that day.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func addDailyThemeHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    requestBody

    Return Value

    HTTP 201 Created if the theme was added successfully.

    Show on GitHub

  • POST /api/v3/admin/dailytheme/ID/edit

    Edits an existing daily theme. Passing nil for the image will remove an existing image. Although you can change the cruise day for a DailyTheme, you can’t set the day to equal a day that already has a theme record. This means it’ll take extra steps if you want to swap days for 2 themes.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func editDailyThemeHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    dailyThemeID

    in URL path
    requestBody

    Return Value

    HTTP 201 Created if the theme was added successfully.

    Show on GitHub

  • POST /api/v3/admin/dailytheme/ID/delete DELETE /api/v3/admin/dailytheme/ID/

    Deletes a daily theme.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func deleteDailyThemeHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    dailyThemeID

    in URL path

    Return Value

    HTTP 204 noContent if the theme was deleted successfully.

    Show on GitHub

  • GET /api/v3/admin/serversettings

    Returns the current state of the server’s Settings structure.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func settingsHandler(_ req: Request) throws -> SettingsAdminData

    Return Value

    SettingsAdminData

    Show on GitHub

  • POST /api/v3/admin/serversettings/update

    Updates a bunch of settings in the Settings.shared object.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func settingsUpdateHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    requestBody

    Return Value

    HTTP 200 OK if the settings were updated.

    Show on GitHub

  • GET /api/v3/admin/timezonechanges

    Returns information about the declared time zone changes happening during the cruise.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func timeZoneChangeHandler(_ req: Request) async throws -> TimeZoneChangeData

    Return Value

    TimeZoneChangeData

    Show on GitHub

  • POST /api/v3/admin/serversettings/reloadtzdata

    Reloads the time zone change data from the seed file. Removes all previous entries.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func reloadTimeZoneChangeData(_ req: Request) async throws -> HTTPStatus

    Return Value

    HTTP 200 OK if the settings were updated.

    Show on GitHub
  • serverRollupCounts(_:) Asynchronous

    GET /api/v3/admin/rollup

    Returns a bunch of summary data about how many rows of certain database objects we’ve created. Useful when we want to check whether a certain row-creating operation is working, whether any operation is creating way more rows than we expect, or just to guage the popularity of various server features.

    More sophisticated servers run an operation like this on a cronjob and analyze the results each time to check that recent db activity matches expectations. Mostly this is just a quick way for us to check usage.

    Declaration

    Swift

    func serverRollupCounts(_ req: Request) async throws -> ServerRollupData
    Show on GitHub

Reg Codes

  • GET /api/v3/admin/regcodes/stats

    Returns basic info about how many regcodes have been used to create accounts, and how many there are in total. In the future, we may add a capability for admins to create and issue replacement codes to users (or pull codes from a pre-allocated ‘replacement’ list, or something). This returns stats on those theoretical codes too, but the numbers are all 0.

    Declaration

    Swift

    func regCodeStatsHandler(_ req: Request) async throws -> RegistrationCodeStatsData
    Show on GitHub

  • GET /api/v3/admin/regcodes/find/:search_string

    Checks whether a user has been associated with a registration code. Can also be used to check whether a reg code is valid. Throws when the reg code is not found primarily to help differentiate between “No reg code found” “No User Found” and “User Found” cases.

    Throws

    400 Bad Request if the reg code isn’t found in the db or if it’s malformed. We don’t check too thoroughly whether it’s well-formed.

    Declaration

    Swift

    func userForRegCodeHandler(_ req: Request) async throws -> [UserHeader]

    Return Value

    [] if no user has created an account using this reg code yet. If they have, returns an array containing the UserHeaders of all users associated with the registration code. The first item in the array will be the primary account.

    Show on GitHub

  • GET /api/v3/admin/regcodes/findbyuser/:userID

    Returns the primary user, all alt users, and registration code for the given user. The input userID can be for the primary user or any of their alts. If called with a userID that has no associated regcode (e.g. ‘admin’ or ‘moderator’), regCode will be “”.

    Throws

    400 Bad Request if the userID isn’t found in the db or if it’s malformed.

    Declaration

    Swift

    func regCodeForUserHandler(_ req: Request) async throws -> RegistrationCodeUserData

    Return Value

    [] if no user has created an account using this reg code yet. If they have, returns a one-item array containing the UserHeader of that user.

    Show on GitHub

  • POST /api/v3/admin/regcodes/discord/allocate/:username

    Finds an unallocated regcode that was reserved for Discord users, allocates it and assigns it to the given Discord user. This method allows TwitarrTeam members to hand out reg codes to be used on the preproduction Twitarr server for account creation, tying those reg codes to a Discord username.

    This method is for Pre-Production only, as the boat server should not have any regcodes reserved for Discord users in its database.

    Declaration

    Swift

    func assignDiscordRegCode(_ req: Request) async throws -> RegistrationCodeUserData
    Show on GitHub

Promote/Demote

  • GET /api/v3/admin/moderators

    Returns a list of all site moderators. Only THO and above may call this method.

    Declaration

    Swift

    func getModeratorsHandler(_ req: Request) async throws -> [UserHeader]

    Return Value

    Array of UserHeader.

    Show on GitHub

  • POST /api/v3/admin/moderator/promote/:user_id

    Makes the target user a moderator. Only admins may call this method. The user must have an access level of .verified and not be temp-quarantined. Unlike the Moderator method that sets access levels, mod promotion only affects the requested account, not other sub-accounts held by the same user.

    Throws

    badRequest if the target user isn’t verified, or if they’re temp quarantined.

    Declaration

    Swift

    func makeModeratorHandler(_ req: Request) async throws -> HTTPStatus

    Return Value

    200 OK if the user was made a mod.

    Show on GitHub

  • POST /api/v3/admin/user/demote/:user_id

    Sets the target user’s accessLevel to .verified if it was .moderator, .twitarrteam, or .tho. Must be THO or higher to call any of these; must be admin to demote THO users.

    Throws

    badRequest if the target user isn’t a mod.

    Declaration

    Swift

    func demoteToVerifiedHandler(_ req: Request) async throws -> HTTPStatus

    Return Value

    200 OK if the user was demoted successfully.

    Show on GitHub

  • GET /api/v3/admin/twitarrteam

    Returns a list of all TwitarrTeam members. Only THO and above may call this method.

    Declaration

    Swift

    func getTwitarrTeamHandler(_ req: Request) async throws -> [UserHeader]

    Return Value

    Array of UserHeader.

    Show on GitHub

  • POST /api/v3/admin/twitarrteam/promote/:user_id

    Makes the target user a member of TwitarrTeam. Only admins may call this method. The user must have an access level of .verified and not be temp-quarantined.

    Throws

    badRequest if the target user isn’t verified, or if they’re temp quarantined.

    Declaration

    Swift

    func makeTwitarrTeamHandler(_ req: Request) async throws -> HTTPStatus

    Return Value

    200 OK if the user was made a mod.

    Show on GitHub
  • getTHOHandler(_:) Asynchronous

    GET /api/v3/admin/tho

    Returns a list of all users with THO access level. Only THO and Admin may call this method.

    THO access level lets users promote other users to Modaerator and TwitarrTeam access, and demote to Banned status. THO users can also post notifications and set daily themes.

    Declaration

    Swift

    func getTHOHandler(_ req: Request) async throws -> [UserHeader]

    Return Value

    Array of UserHeader.

    Show on GitHub
  • makeTHOHandler(_:) Asynchronous

    POST /api/v3/admin/tho/promote/:user_id

    Makes the target user a member of THO (The Home Office). Only admins may call this method. The user must have an access level of .verified and not be temp-quarantined.

    Throws

    badRequest if the target user isn’t verified, or if they’re temp quarantined.

    Declaration

    Swift

    func makeTHOHandler(_ req: Request) async throws -> HTTPStatus

    Return Value

    200 OK if the user was made a mod.

    Show on GitHub
  • getUsersWithRole(_:) Asynchronous

    GET /api/v3/admin/userroles/:user_role

    Returns a list of all users that have the given role.

    Declaration

    Swift

    func getUsersWithRole(_ req: Request) async throws -> [UserHeader]

    Return Value

    Array of UserHeader.

    Show on GitHub
  • addRoleForUser(_:) Asynchronous

    POST /api/v3/admin/userroles/:user_id/addrole/:user_role

    Adds the given role to the given user’s role list. Only THO and above may call this method.

    Throws

    badRequest if the target user already has the role.

    Declaration

    Swift

    func addRoleForUser(_ req: Request) async throws -> HTTPStatus

    Return Value

    200 OK if the user now has the given role.

    Show on GitHub
  • removeRoleForUser(_:) Asynchronous

    POST /api/v3/admin/userroles/:user_id/removerole/:user_role

    Removes the given role from the target user’s role list. Only THO and above may call this method.

    Throws

    badRequest if the target user isn’t a Karaoke Manager.

    Declaration

    Swift

    func removeRoleForUser(_ req: Request) async throws -> HTTPStatus

    Return Value

    200 OK if the user was demoted successfully.

    Show on GitHub

Schedule Updating

  • POST /api/v3/admin/schedule/update

    Handles the POST of a new schedule .ics file.

    Warning

    Updating the schedule isn’t thread-safe, especially if admin is logged in twice. Uploading a schedule file while another admin account was attempting to apply its contents will cause errors. Once uploaded, an events file should be safe to verify and apply multiple times in parallel.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func scheduleUploadPostHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    requestBody

    EventsUpdateData which is really one big String (the .ics file) wrapped in JSON.

    Return Value

    HTTP 200 OK

    Show on GitHub

  • GET /api/v3/admin/schedule/verify

    Returns a struct showing the differences between the current schedule and the (already uploaded and saved to a local file) new schedule.

    Note

    This is a separate GET call, instead of the response from POSTing the updated .ics file, so that verifying and applying a schedule update can be idempotent. Once an update is uploaded, you can call the validate and apply endpoints repeatedly if necessary.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func scheduleChangeVerificationHandler(_ req: Request) async throws -> EventUpdateDifferenceData
    Show on GitHub

  • POST /api/v3/admin/schedule/update/apply

    Applies schedule changes to the schedule. Reads in a previously uploaded schedule file from /admin/uploadschedule.ics and creates, deletes, and updates Event objects as necessary. If forumPosts is true, creates posts in Event forums notifying users of the schedule change. Whether forumPosts is true or not, forums are created for new Events, and forum titles and initial posts are updated to match the updated event info.

    URL Query Parameters:

    • ?processDeletes=true to delete existing events not in the update list. Only set this if the update file is a comprehensive list of all events.

    • ?forumPosts=true to create posts in the Event Forum of each modified event, alerting readers of the event change. We may want to forego change posts if we update the schedule as soon as we board the ship. For events created by this update, we always try to create and associate a forum for the event.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func scheduleChangeApplyHandler(_ req: Request) async throws -> HTTPStatus

    Return Value

    HTTP 200 OK

    Show on GitHub

  • GET /api/v3/admin/schedule/viewlog

    Gets the last 100 entries in the schedule update log, showing what the automatic (and manual) updates to the schedule have been doing.

    Declaration

    Swift

    func scheduleChangeLogHandler(_ req: Request) async throws -> [EventUpdateLogData]

    Return Value

    [EventUpdateLogData] the most recent 100 log entries, in descending order of update time.

    Show on GitHub

  • GET /api/v3/admin/schedule/viewlog/:log_id

    ** Parameters:**

    • :log_id the ID of the schedule change log entry to return.

    NOTE: Unless you’ve requested the most recent change, the returned data may not match the state of the schedule in the db.

    Declaration

    Swift

    func scheduleGetLogEntryHandler(_ req: Request) async throws -> EventUpdateDifferenceData

    Return Value

    EventUpdateDifferenceData showing what events were modified by this change to the schedule

    Show on GitHub

  • GET /api/v3/admin/schedule/reload

    Trigger a reload of the Sched event schedule. Normally this happens automatically every hour.

    Declaration

    Swift

    func reloadScheduleHandler(_ req: Request) async throws -> HTTPStatus

    Return Value

    HTTP 200 OK.

    Show on GitHub

Bulk User Update

  • GET /api/v3/admin/bulkuserfile/download

    Handles the GET of a userfile. A userfile is a zip file continaing a bunch of user records, with profile data and avatars. Intended to be used to facilitate server-to-server transfer of users.

    Warning: Uses blocking IO–the thing that isn’t great for multithreaded servers.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

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

    Parameters

    requestBody

    EventsUpdateData which is really one big String (the .ics file) wrapped in JSON.

    Return Value

    HTTP 200 OK

    Show on GitHub

  • POST /api/v3/admin/bulkuserfile/upload

    Handles the POST of a new userfile.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func userfileUploadPostHandler(_ req: Request) async throws -> HTTPStatus

    Parameters

    requestBody

    Data of the zip'ed userfile..

    Return Value

    HTTP 200 OK

    Show on GitHub

  • GET /api/v3/admin/bulkuserfile/verify

    Returns a struct showing the differences between the current schedule and the (already uploaded and saved to a local file) new schedule.

    Note

    This is a separate GET call, instead of the response from POSTing the updated .ics file, so that verifying and applying a schedule update can be idempotent. Once an update is uploaded, you can call the validate and apply endpoints repeatedly if necessary.

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func userfileVerificationHandler(_ req: Request) async throws -> BulkUserUpdateVerificationData
    Show on GitHub

  • POST /api/v3/admin/bulkuserfile/update/apply

    Throws

    A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func userfileApplyHandler(_ req: Request) async throws -> BulkUserUpdateVerificationData

    Return Value

    HTTP 200 OK

    Show on GitHub

Utilities