Prune Old Event Forums

In long-lived Swiftarr instances such as the Beta, we typically do not reset the database between sailings. As we accumulate years of events, the amount of forums starts to grow unweildy. The old events are marked as deleted and removed from the schedule, but the forums remain. This backend command is intended to be executed by an operator in one of these long-lived environments to soft-delete all forums that are linked to soft-deleted events.

The effects of this command can be reversed by importing the deleted schedule again which will restore the events and their associated forums (thanks, soft-delete).

Random number generator that can be initialized with a seed value. Copied from https://github.com/mattgallagher/CwlUtils/blob/master/Sources/CwlUtils/CwlRandom.swift

The idea here is that this RNG is seeded with a user’s userID, and will always produce the same sequence of numbers when building a user’s identicon..

The collection of /api/v3/performer/* route endpoints and handler functions related to the official performers and shadow event organizers..

The collection of /api/v3/personalevents/* route endpoints and handler functions related to events that are specific to individual users.

Used during bulk import of User information. Reports the result of merging the new User data into the database, or for the Verify operation, previews what that result will be.Purposefully does not report specific regCodes that are in conflict.

The idea behind this struct is to split out cases where we might get 1000+ errors under certain import conditions, so we don’t just return an array of Errors where there’s one important error buried in a thousand ‘duplicate name and regcode’ errors.

For admins to upload new daily themes, or edit existing ones.

Used to validate changes to the Event database. This public struct shows the differrences between the current schedule and the (already uploaded but not processed) updated schedule. Event identity is based on the uid field–two events with the same uid are the same event, and if they show different times, we conclude the event’s time changed. Two events with different uids are different events, even if all other fields are exactly the same.

Events that are added or deleted will only appear in deleted or created event arrays. Modified events could appear in any or all of the 3 modification arrays. Deleted events take their contents from the database. All other arrays take content from the update.

Required by: POST /api/v3/admin/schedule/verify

See EventController.eventsUpdateHandler(_:data:).

Used to report what the results of applying an update to the Event-Performer pivots is going to do. The uploaded source information is an Excel spreadsheet containing all the published events, with information on which official performers (if any) will be performing at each event.

When uploading a new performer links spreadsheet, it’s important that both Events and Performers are fully updated first. This operation doesn’t create performers or events, just links them with a pivot.

Returned by: POST /api/v3/admin/schedule/verify

Returns the registration code associated with a user. Not all users have registration codes; e.g. asking for the reg code for ‘admin’ will return an error.

Returns general info about registration codes.

Each passenger gets sent an email with a unique registration code; the reg code allows them to create verified accounts. This struct lets the admins quickly view some basic stats on account usage.

The Bulk User Download file is a serialization of this object, plus a bunch of image files, all zipped up.

An array of totals for various database entities. Each value in the array is essentially a SQL SELECT COUNT() FROM <table>, although some values apply filters to the counted rows.

The CountType enum defines what each value in the counts array means, so counts[0] is a count of the Users in the database.

Used by: GET /api/v3/admin/rollup

Used to enable/disable features. A featurePair with name: “kraken” and feature: “schedule” indicates the Schedule feature of the Kraken app. When the server indicates this app:feature pair is disabled, the client app should not show the feature to users, and should avoid calling API calls related to that feature. Either the app or feature field could be ‘all’.

Used in: SettingsAdminData, SettingsUpdateData

Used to return the current Settings values.

Required by: GET /api/v3/events/update

See AdminController.settingsHandler().

Used to update the Settings values. Doesn’t update everything–some values aren’t meant to be updated live. The updated values are saved so that they’ll persist through app launches. Any optional values set to nil are not used to update Settings values.

Required by: POST /api/v3/events/update

See AdminController.settingsUpdateHandler().

Used to return information about the time zone changes scheduled to occur during the cruise.

Returned by: GET /api/v3/admin/timezonechanges

Used to bulk save/restore user accounts. This was created to allow us to download an archive of all registered users from the staging server just before embarkation, and then load the archived users onto the prod server as soon as we get on the boat.

Just archiving Users directly would work, but using a DTO gives us better control in the case of schema changes between staging and prod, or if we need to massage the data to get the restore to work correctly. Also, this method tries whenever possible to put data from related tables we want to save/restore right in the User object; otherwise we’d have to export RegistrationCode and EventFavorite(and maybe a bunch of other tables) and match everything up as part of import.

Also: This DTO contains sensitive data and should only be used for Admin routes.

Parameters for the game recommender engine. Pass these values in, get back a BoardgameResponseData with a list of games filtered to match the criteria, and sorted based on how well they match the criteria. The sort takes into account each games’ overall rating from BGG, the recommended number of players (not just min and max allowed players), the average playtime, and the complexity score of the game.

Sent to these methods as the JSON request body:

• GET /api/v3/boardgames/recommend

Used to return the day’s theme.

Returned by: GET /api/v3/notifications/dailythemes

A feature that has been turned off by the server. If the appName is all, the indicated featureName is disabled at the API level for this feature and all relevant endpoints will return errors. For any other value of appName, the API still works, but the indicated client apps should not allow the feature to be accessed. The goal is to be able to disable code that is impacting server stability or performance without shutting down the server entirely or disallowing specific clients entirely.

Used in UserNotificationData.

All errors returned in HTTP responses use this structure.

Some server errors (such as 404s) may not have any payload in the response body, but for any HTTP error response that has a payload, the payload will have this strcture.

error is always true, reason concatenates all errors into a single string, and fieldErrors breaks errors up by field name of the request’s body content, if available. Only content validation errors actaully use fieldErrors. Field-specific validation errors are keyed by the path to the field that caused the error. Validation errors that aren’t specific to an input field (e.g. an error indicating that one of two fields may be empty, but not both) are all concatenated and placed into a general key in fieldErrors. This means that all field errors are both in error (concatenated into a single string), and also in fieldErrors (split into fields).

Used to return data on a group of FriendlyFez objects.

Used to return a (partial) list of forums along with the number of forums in the found set. Similar to CategoryData, but the forums need not be from the same category. Instead, this returns forums that match a common attribute acoss all categores.

Returned by:

• GET /api/v3/forum/favorites
• GET /api/v3/forum/owner

See ForumController.categoriesHandler(_:)

Wraps an array of KaraokeSongData with information for pagination. KaraokeSongData returns data about a single song.

Returned by: GET /api/v3/karaoke See KaraokeController.getKaraokeSongs().

Returns information about a song in the Karaoke Song Library.

Returned by: GET /api/v3/karaoke/:song_id Incorporated into: KaraokeSongResponseData

Returns information about songs that have been performed in the Karaoke Lounge onboard.

Returned by: GET /api/v3/karaoke/performance Incorporated into: KaraokeSongData, which itself is incorporated into KaraokeSongResponseData

Returns information about songs that have been performed in the Karaoke Lounge onboard.

Returned by: GET /api/v3/karaoke/performance Incorporated into: KaraokeSongData, which itself is incorporated into `KaraokeSongResponseData

Used to obtain the user’s current list of alert or mute keywords.

Returned by:

• GET /api/v3/user/alertwords
• POST /api/v3/user/alertwords/add/STRING
• POST /api/v3/user/alertwords/remove/STRING
• GET /api/v3/user/mutewords
• POST /api/v3/user/mutewords/add/STRING
• POST /api/v3/user/mutewords/remove/STRING

See UserController.alertwordsHandler(_:), UserController.alertwordsAddHandler(_:), UserController.alertwordsRemoveHandler(_:).

Used to return a list of completed Micro Karaoke songs, that is, finished videos the user can watch.

Returned by:

• GET /api/v3/karaoke/mk/songlist

See UsersController.headerHandler(_:), ClientController.userHeadersHandler(_:).

Used to upload a Micro Karaoke video. The offerID comes from the server when it offers a song clip.

Used by:

• POST /api/v3/karaoke/mk/recording

When a user starts the Micro Karaoke flow to sing and record part of a song, the server reserves a song slot for that user and returns into about their reservation, including the lyrics they should sing, what song it’s part of, and URLs for the vocal and no-vocal song clipe.

Returned by:

• POST /api/v3/karaoke/mk/offer

Composes into other structs to add pagination.

Generally this will be added to a top-level struct along with an array of some result type, like this:

    struct SomeCollectionData: Content {
        var paginator: Paginator
        var collection: [CollectionElementType]
    }

The Paginator lets you page through results, showing the total number of pages and the current page. The outer-level struct should document the sort ordering for the returned collection; the first element in the sorted collection is returned in the first result element when start = 0.

In many cases the size of the returned array will be smaller than limit, and not only at the end of the results. In several cases the results may be filtered after the database query returns. The next ‘page’ of results should be calculated with start + limit, not with start + collection.count.

This simple generic lets us declare route result types as Paginated<ContentType>, where ContentType is an array of some Content struct (probably found in this file). This simplifies writing paginated reults as we don’t need to create a separate struct just to hold the paginator, but it may make the structs more opaque, especially to those that don’t know Swift. Part of the idea of this file was to make it easy for developers to understand the JSON that would be emitted by these structs.

Returns info about a single Performer. This header information is similar to the UserHeader structure, containing just enough info to build a title card for a performer.

This structure is also used to break the recusion cycle where a PerformerData contains a list of Events, and the Events contain lists of the Performers that will be there. In this case, the Event has an array of PerformerHeaderData instead of PerformerData.

Incorporated into PerformerData Incorporated into EventData

Returns info about a single perfomer. Most fields are optional, and the array fields may be empty, although they shouldn’t be under normal conditions.

Returned by: GET /api/v3/performer/self Returned by: GET /api/v3/performer/:performer_id

Wraps up a list of performers with pagination info.

Returned by:GET /api/v3/performer/official Returned by:GET /api/v3/performer/shadow

Used to create and update Performer models.

Used by: POST /api/v3/performer/forEvent/:event_id Used by: POST /api/v3/performer/official/add

Returns info about a single Photo from the Photostream.

Incorporated into PhotostreamListData, which is returned by: GET /api/v3/photostream

Returns paginated data on photos in the photo stream. Non-Mods should only have access to the most recent photos, with no pagination. However: /api/v3/photostream returns one of thse objects even for non-mod users–it just returns 30 photos and sets paginator.total to 30.

Returned by: GET /api/v3/photostream

Returns information on available tags to use when tagging a photo to be uploaded to the photostream. A photo may be tagged with an event or with a generic ship location. Calling api/v3/photostream/placenames fills the events parameter with information about events that are currently happening. When a photo is uploaded, its tag is validated, and validation will fail if the tagged event has ended.

Returned by: GET /api/v3/photostream

Uploads a photo to the photostream. Either the eventID or the locationName must be set.

Sent in request body to: POST /api/v3/photostream/upload.

Used to return info about a search for ForumPosts. Like forums, this returns an array of PostData. However, this gives the results of a search for posts across all the forums.

Returned by: GET /api/v3/forum/post/search

A bool, wrapped in a struct. Used for the results of user capability queries.

Required by:

• POST /api/v3/karaoke/userIsManager

See UserController.createHandler(_:data:), UserController.addHandler(_:data:).

Returns status about a single Alertword, for either Twarrts of ForumPost hits on that word. Used inside UserNotificationData.

Provides updates about server global state and the logged in user’s notifications. userNotificationHandler() is intended to be called frequently by clients (I mean, don’t call it once a second).

Returned by AlertController.userNotificationHandler()

Used to edit the current user’s profile contents. For profile data on users, see ProfilePublicData.

Required by:

• POST /api/v3/user/profile

Returned by:

• GET /api/v3/user/profile
• POST /api/v3/user/profile

See UserController.profileHandler(_:), UserController.profileUpdateHandler(_:data:).

Prometheus Alertmanager webhook alert object. Applied from https://prometheus.io/docs/alerting/latest/configuration/#webhook_config

Prometheus Alertmanager webhook payload. Applied from https://prometheus.io/docs/alerting/latest/configuration/#webhook_config

Healthcheck URL response payload. This smells roughly the same as an error fields-wise without inheriting from the error.

Used to return a PersonalEvent‘s data.

PersonalEventContentData is used for creating and editing a PersonalEvent. Contains all of the fields that a user can modify.

Used to return FriendlyFezEdit data for moderators. The only primary data an edit stores is the title, info, and location text fields.

Included in:

• FezModerationData

Returned by:

• GET /api/v3/mod/fez/ID

Used to return data a moderator needs to moderate a fez.

Returned by:

• GET /api/v3/mod/fez/:fez_id

Note that FezPosts can’t be edited and don’t have an edit log.

See ModerationController.fezModerationHandler(_:)

Used to return data a moderator needs to moderate a fez post.

Returned by:

• GET /api/v3/mod/fezpost/:post_id

See ModerationController.fezPostModerationHandler(_:)

Used to return ForumEdit data for moderators. ForumEdit only stores the title and category the forum had before the edit.

Included in:

• ForumModerationData

Returned by:

• GET /api/v3/mod/forum/id

Used to return data a moderator needs to moderate a forum.

Returned by:

• GET /api/v3/mod/forum/id

See ModerationController.forumModerationHandler(_:)

Used to return data a moderator needs to moderate a twarrt.

Returned by:

• GET /api/v3/mod/forumPost/id

See ModerationController.forumPostModerationHandler(_:)

Returns data about an instance of a moderator using their mod powers to edit/delete a user’s content, edit a user’s profile fields, or change a user’s privledges.

Used to return data on a collection of moderator action events.

Used to return mod data on a Photostream photo

Used to return a TwarrtEdit or ForumPost‘s data for moderators. The two models use the same data structure, as all the fields happen to be the same.

Included in:

• ForumPostModerationData
• TwarrtModerationData

Returned by:

• GET /api/v3/mod/twarrt/id

Used to return data moderators need to view previous edits a user made to their profile. This structure will have either the profileData or profileImage field populated. An array of these stucts is placed inside ProfileModerationData.

Used to return data moderators need to evaluate a user’s profile. Shows the user’s current profile values, past edits, reports made against the profile, and the user’s profile moderationStatus.

Used to return data about Reports submitted by users. Only Moderators and above have access.

Required by:

• GET /api/v3/mod/reports

Used to return data a moderator needs to moderate a twarrt.

Returned by:

• GET /api/v3/mod/twarrt/id

See ModerationController.twarrtModerationHandler(_:)

Used to return data a moderator needs to moderate a user.

Returned by:

• GET /api/v3/mod/user/id

See ModerationController.userModerationHandler(_:)

Used to return data a moderator needs to moderate a PersonalEvent.

Returned by:

• GET /api/v3/mod/personalevent/id

See ModerationController.personalEventModerationHandler(_:)

FezPostData, modified to be easier for sockets.

Fez and Seamail socket clients will receive this message as a JSON string when a user posts in the fez/seamail. Posts made by a user will be reflected back to them via this socket. If a user is logged on from 2 clients and both have open sockets, both clients will see the socket message when the user posts a new message from one of the clients. Each struct contains the UserHeader of the poster instead of the author’s UUID; this way clients (okay, the javascript web client) can format the post without additional requests.

Note: Fezzes have other state changes that don’t currently have websocket notifications. Your socket message handler should gracefully handle the possibility that you receive a message that doesn’t fit any of the currently documented message structs.

See:

• WS /api/v3/fez/:fezID/socket

Informs Fez WebSocket clients of a change in Fez membership.

If joined is FALSE, the user has left the fez. Although seamail sockets use the same endpoint (seamail threads are Fezzes internally), this mesage will never be sent to Seamail threads as membership is fixed at creation time.

Fez socket message handlers will receive this message as a JSON string when a user joins/leaves the fez, or is added/removed by the fez owner.

See:

• WS /api/v3/fez/:fezID/socket

Informs Notification WebSocket clients of a new notification.

Each notification is delivered as a JSON string, containing a type of announcement and a string appropriate for displaying to the user. The string will be of the form, “User @authorName wrote a forum post that mentioned you.”

Notifies the recipient of a phone call the IP addr of the caller, so the recipient can open a direct-connect WebSocket to the caller (who must have started a WebSocket Server to receive the incoming connection).

Sent at the start of a phone call. Used as a handshake.

Defines a formatter to be used on BMP import & export conversions

Defines a formatter to be used on GIF import & export conversions

Defines a formatter to be used on JPEG import & export conversions

Defines a formatter to be used on PNG import & export conversions

Defines a formatter to be used on TIFF import & export conversions

Defines a formatter to be used on TGA import & export conversions

Defines a formatter to be used on WBMP import & export conversions

Defines a formatter to be used on WEBP import & export conversions

A structure that represents a geometric angle.

A structure that contains a point in a two-dimensional coordinate system.

A structure that represents a rectangle.

A structure that represents a two-dimensional size.

AsyncJobs require a payload, and apparently we can’t just shove Codable at it. So this struct exists in case the job ever decides to need runtime parameters.

Job to update the Sched schedule on a “cron” (and by “cron” I mean Vapor Queue).

Job to update the Sched schedule on demand.

Job to push socket notifications of an upcoming event on a “cron” (and by “cron” I mean Vapor Queue).

Structure of the JSON in the JoCoGamesCatalog file.

Similar to the structure of the Model object (Boardgame) and the Data Transfer Sruct (BoardgameData), but this struct is specifically for migration.

A Migration that imports timezone change data located in the seeds/ subdirectory of the project. The time-zone-changes.txt file should contain tab-delimited data, 3 fields on each line: 20220305T070000Z -5 EST This line says that on March 5, 2022 at 2:00 AM EST (7 AM UTC), the boat will be in the EST timezone, with a timezone offset of -5 hours. Because we usually use the previous year’s schedule data for testing until we get the next year’s schedule, it’s intended that the time-zone-changes.txt file will have more than one sailing’s worth of timezone changes in it.

This migration used to include populating the last_post_id for all existing rows. Except that acting on Forum before all future migrations have executed (as listed in configure.swift) fails because all of the other fields don’t exist yet. So that functionality has been moved to PopulateForumLastPostIDMigration below and that migration runs later on after all schema modifications have been populated.

Context required for a paginator control. A page may include “paginator.leaf” multiple times to place multiples of the same paginator, but the context is set up to only allow one paginator per page, at a path of “/paginator” from the context root. I could enforce this with a protocol, but … meh.

Runs the element sanitizer on the given string, and then converts Jocomoji (specific string tags with the form :tag:) into inline images. Generally, use this tag for user text that isn’t posts.

Usage: #addJocomoji(String) -> String

Renders arbitrary Markdown text

Usage: #markdownTextTag(String) -> String

Runs the element sanitizer on the given string, converts Jocomoji (specific string tags with the form :tag:) into inline images, and then converts substrings of the forum “@username” and “#hashtag” into links.

Usage: #formatTwarrtText(String) -> String Usage: #formatPostText(String) -> String Usage: #formatFezText(String) -> String Usage: #formatSeamailText(String) -> String

Turns a Date string into a relative date string. Argument is a ISO8601 formatted Date, or what JSON encoding does to Date values. Output is a string giving a relative time in the past (from now) indicating the approximate time of the Date.

Output is constrained to a single element. e.g: “3 hours ago”, “1 day ago”, “5 minutes ago”

Usage in Leaf templates: #relativeTime(dateValue) -> String

Returns a string descibing when an event is taking place. Shows both the start and end time.

Events come to us from the Sched dump which THO populates as “consistent-boat-EST-based-UTC”. Meaning that the raw values from Sched are in UTC and the events are scheduled for EST and not adjusted for any time-zone changes. This means that on any day where the boat (display) time zone changes the Sched is off by that offset. Since EST is given as the reference point for timezoneless time on the ship we call that “Port Time” and always render events based on that perspective so that it will be consistent.

For 2022 a munger was developed so that the days of odd time zones get their UTC times adjusted by the difference between Port Timezone and AST (which was our only transition). As such there is currently no functional difference between EvenTimeTag and FezTimeTag. It is being left in the code so that some day we can define programatic timezone transitions and not have to do munging of the input.

Usage in Leaf templates:: #eventTime(startTime, endTime) -> String

Returns a string descibing when an LFG is taking place. Shows both the start and end time.

Usage in Leaf templates:: #fezTime(startTime, endTime) -> String

Returns a string describing a time. Unlike EventTimeTag this is used for a single point in time rather than a range or duration.

Usage in Leaf templates:: #staticTime(startTime) -> String

Returns a string describing a time, expressed as a ISO8601 time string in the GMT timezone. That is: 20221103T002152Z.

Usage in Leaf templates:: #UTCTime(time) -> String

Return an ISO8601-ish time string for use with the HTML datetime-local form input type. It cannot take an ISO8601 since that requires a timezone to be included (suffix of [+-]H:MM) and the input chokes on that. So here we translate the following:

“2022-02-13 02:00:00 +0000” (Date) -> “2022-02-12T18:00:00” (String)

Turns a Date into a indexed day of the cruise, with embarkation day being day 0. Used to get the day on which an event happens. This code counts “days’ as starting/ending at 3AM instead of midnight, as there are often after-midnight events but rarely 3AM events.

Usage: #cruiseDayIndex(date) returns 0…8

Inserts an tag for the given user’s avatar image. Presents a default image if the user doesn’t have an image. Note: If we implement identicons at the API level, users will always have images, and the ‘generic user’ image here is just a fallback.

First parameter is the UserHeader, second optional parameter is the size of the to produce. This tag will select the best size image to reference based on the size of the image tag it is being placed in. Only produces square image views.

Usage: #avatar(userHeader), #avatar(userHeader, 800)

Inserts an tag with the given user’s display name and username, linking to the user’s profile page. As an UnsafeUnescaped tag, needs to sanitize user-provided text itself.

Prints a float with 2 decimal precision e.g. “5.76”. Used by game ratings and game complexity.

Usage: #gameRating(float)

https://github.com/jocosocial/swiftarr/issues/188 Renders a pretty label for a dinner team enum. I have to believe there’s a better way to access fancy properties like dinnerTeam.label from within the template, but I didn’t see an obvious pattern that worked.

Launching Swiftarr

Environment

Besides the standard .development, .production, and .testing, there’s a few custom environment values that can be set, either on the command line with --env <ENVIRONMENT> or with the VAPOR_ENV environment variable

Environment variables used by Swiftarr:

• DATABASE_URL:
• DATABASE_HOSTNAME:
• DATABASE_PORT:
• DATABASE_DB:
• DATABASE_USER:

• DATABASE_PASSWORD:

• REDIS_URL:

• REDIS_HOSTNAME:

• PORT:

• hostname:

• ADMIN_PASSWORD:

• RECOVERY_KEY:

• SWIFTARR_USER_IMAGES: Root directory for storing user-uploaded images. These images are referenced by filename in the db.

• SWIFTARR_EXTERNAL_URL: Externally-visible URL to get to the server. The server uses this to create URLs pointing to itself.