FezController

struct FezController : APIRouteCollection

The collection of /api/v3/fez/* route endpoints and handler functions related to Looking For Group and Seamail chats.

Show on GitHub

Retrieving Fezzes

  • /GET /api/v3/fez/types

    Retrieve a list of all values for FezType as strings.

    Declaration

    Swift

    func typesHandler(_ req: Request) throws -> [String]

    Return Value

    An array of String containing the .label value for each type.

    Show on GitHub
  • openHandler(_:) Asynchronous

    GET /api/v3/fez/open

    Retrieve FriendlyFezzes with open slots and a startTime of no earlier than one hour ago. Results are returned sorted by start time, then by title.

    URL Query Parameters:

    • ?cruiseday=INT - Only return fezzes occuring on this day of the cruise. Embarkation Day is day 0.
    • ?type=STRING - Only return fezzes of this type, there STRING is a FezType.fromAPIString() string.
    • ?start=INT - The offset to the first result to return in the filtered + sorted array of results.
    • ?limit=INT - The maximum number of fezzes to return; defaults to 50.

    • ?hidepast=BOOLEAN - Show fezzes that started more than one hour in the past. For this endpoint, this defaults to TRUE.

    Throws

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

    Declaration

    Swift

    func openHandler(_ req: Request) async throws -> FezListData

    Return Value

    An array of FezData containing current fezzes with open slots.

    Show on GitHub
  • joinedHandler(_:) Asynchronous

    GET /api/v3/fez/joined

    Retrieve all the FriendlyFez chats that the user has joined. Results are sorted by descending fez update time.

    Query Parameters:

    • ?cruiseday=INT - Only return fezzes occuring on this day of the cruise. Embarkation Day is day 0.
    • ?type=STRING - Only return fezzes of the given fezType. See FezType for a list.
    • ?excludetype=STRING - Don’t return fezzes of the given type. See FezType for a list.
    • ?onlynew=TRUE - Only return fezzes with unread messages.
    • ?start=INT - The offset to the first result to return in the filtered + sorted array of results.
    • ?limit=INT - The maximum number of fezzes to return; defaults to 50.
    • ?search=STRING - Only show fezzes whose title, info, or any post contains the given string.
    • ?hidepast=BOOLEAN - Hide fezzes that started more than one hour in the past. For this endpoint, this defaults to FALSE.
    • ?matchID=UUID - Returns a single LFG with the given ID.
    • ?lfgtypes=BOOLEAN - Shorthand to include/exliude all the LFG types (Activity, Gaming, Dining, etc.) Acts the same as using multiple type= or exludetype= params.

    Moderators and above can use the foruser query parameter to access pseudo-accounts:

    • ?foruser=NAME - Access the “moderator” or “twitarrteam” seamail accounts.

    /GET /api/v3/fez/types is the canonical way to get the list of acceptable values. Type and excludetype are exclusive options, obv.

    Throws

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

    Declaration

    Swift

    func joinedHandler(_ req: Request) async throws -> FezListData

    Return Value

    An array of FezData containing all the fezzes joined by the user.

    Show on GitHub
  • ownerHandler(_:) Asynchronous

    GET /api/v3/fez/owner

    Retrieve the FriendlyFez chats created by the user.

    Note

    There is no block filtering on this endpoint. In theory, a block could only apply if it were set after the fez had been joined by the second party. The owner of the fez has the ability to remove users if desired, and the fez itself is no longer visible to the non-owning party.

    Query Parameters:

    • ?cruiseday=INT - Only return fezzes occuring on this day of the cruise. Embarkation Day is day 0.
    • ?type=STRING - Only return fezzes of the given fezType. See FezType for a list.
    • ?excludetype=STRING - Don’t return fezzes of the given type. See FezType for a list.
    • ?start=INT - The offset to the first result to return in the filtered + sorted array of results.
    • ?limit=INT - The maximum number of fezzes to return; defaults to 50.
    • ?hidepast=BOOLEAN - Hide fezzes that started more than one hour in the past. For this endpoint, this defaults to FALSE.

    • ?lfgtypes=BOOLEAN - Shorthand to include/exliude all the LFG types (Activity, Gaming, Dining, etc.) Acts the same as using multiple type= or exludetype= params.

    Throws

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

    Declaration

    Swift

    func ownerHandler(_ req: Request) async throws -> FezListData

    Return Value

    An array of FezData containing all the fezzes created by the user.

    Show on GitHub
  • fezHandler(_:) Asynchronous

    GET /api/v3/fez/:fez_ID

    Retrieve information about the specified FriendlyFez. For users that aren’t members of the fez, this info will be the same as the info returned for GET /api/v3/fez/open. For users that have joined the fez the FezData.MembersOnlyData will be populated, as will the FezPosts.

    Query Parameters:

    • ?start=INT - The offset to the first post to return in the array of posts.
    • ?limit=INT - The maximum number of posts to return; defaults to 50.

    Start and limit only have an effect when the user is a member of the Fez. Limit defaults to 50 and start defaults to (readCount / limit) * limit, where readCount is how many posts the user has read already.

    Moderators and above can use the foruser query parameter to access pseudo-accounts:

    • ?foruser=NAME - Access the “moderator” or “twitarrteam” seamail accounts.

    When a member calls this method, it updates the member’s readCount, marking all posts read up to start + limit. However, the returned readCount is the value before updating. If there’s 5 posts in the chat, and the member has read 3 of them, the returned FezData has 5 posts, we return 3 in FezData.readCountfield, and update the pivot’s readCount to 5.

    FezPosts are ordered by creation time.

    Note

    Posts are subject to block and mute user filtering, but mutewords are ignored in order to not suppress potentially important information.

    Throws

    404 error if a block between the user and fez owner applies. A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func fezHandler(_ req: Request) async throws -> FezData

    Parameters

    fezID

    in the URL path.

    Return Value

    FezData with fez info and all discussion posts.

    Show on GitHub

  • GET /api/v3/fez/former

    Query Parameters:

    • ?start=INT - The offset to the first post to return in the array of posts.
    • ?limit=INT - The maximum number of posts to return; defaults to 50.

    Retrieve information about (open) Seamails, Private Events, and LFGs the user was previously a member of, but no longer. Won’t return info on closed Seamails or Personal Events as their member lists cannot change.

    Declaration

    Swift

    func formerlyJoinedFezHandler(_ req: Request) async throws -> FezListData
    Show on GitHub

Membership

  • joinHandler(_:) Asynchronous

    POST /api/v3/fez/ID/join

    Add the current user to the FriendlyFez. If the .maxCapacity of the fez has been reached, the user is added to the waiting list.

    Note

    A user cannot join a fez that is owned by a blocked or blocking user. If any current participating or waitList user is in the user’s blocks, their identity is replaced by a placeholder in the returned data. It is the user’s responsibility to examine the participant list for conflicts prior to joining or attending.

    Throws

    400 error if the supplied ID is not a fez barrel or user is already in fez. 404 error if a block between the user and fez owner applies. A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

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

    Parameters

    fezID

    in the URL path.

    Return Value

    FezData containing the updated fez data.

    Show on GitHub
  • unjoinHandler(_:) Asynchronous

    POST /api/v3/fez/ID/unjoin

    Remove the current user from the FriendlyFez. If the .maxCapacity of the fez had previously been reached, the first user from the waiting list, if any, is moved to the participant list.

    Throws

    400 error if the supplied ID is not a fez barrel. A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func unjoinHandler(_ req: Request) async throws -> FezData

    Parameters

    fezID

    in the URL path.

    Return Value

    FezData containing the updated fez data.

    Show on GitHub

Posts

  • postAddHandler(_:) Asynchronous

    POST /api/v3/fez/ID/post

    Add a FezPost to the specified FriendlyFez.

    Open fez types are only permitted to have 1 image per post. Private fezzes (aka Seamail) cannot have any images.

    Throws

    404 error if the fez is not available. A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func postAddHandler(_ req: Request) async throws -> FezPostData

    Parameters

    fezID

    in URL path
    requestBody

    Return Value

    FezPostData containing the user’s new post.

    Show on GitHub
  • postDeleteHandler(_:) Asynchronous

    POST /api/v3/fez/post/ID/delete DELETE /api/v3/fez/post/ID

    Delete a FezPost. Must be author of post.

    Throws

    403 error if user is not the post author. 404 error if the fez is not available. A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

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

    Parameters

    fezID

    in URL path

    Return Value

    HTTP 204 No Content

    Show on GitHub

  • POST /api/v3/fez/post/ID/report

    Creates a Report regarding the specified FezPost.

    Note

    The accompanying report message is optional on the part of the submitting user, but the ReportData is mandatory in order to allow one. If there is no message, send an empty string in the .message field.

    Throws

    400 error if the post is private.

    Throws

    404 error if the parent fez of the post could not be found.

    Declaration

    Swift

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

    Parameters

    postID

    in URL path, the ID of the post being reported.
    requestBody

    ReportData payload in the HTTP body.

    Return Value

    201 Created on success.

    Show on GitHub

Fez Management

  • createHandler(_:) Asynchronous

    POST /api/v3/fez/create

    Create a FriendlyFez. The creating user is automatically added to the participant list.

    The list of recognized values for use in the .fezType field is obtained from GET /api/v3/fez/types.

    The startTime, endTime, and location fields are optional. Pass nil for these fields if the values are unknown/not applicable. Clients should convert nils in these fields to “TBD” for display.

    Important

    Do not pass “0” as the date value. Unless you really are scheduling something for the first stroke of midnight in 1970.

    A value of 0 in either the .minCapacity or .maxCapacity fields indicates an undefined limit: “there is no minimum”, “there is no maximum”.

    Throws

    400 error if the supplied data does not validate.

    Declaration

    Swift

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

    Parameters

    requestBody

    FezContentData payload in the HTTP body.

    Return Value

    201 Created; FezData containing the newly created fez.

    Show on GitHub
  • cancelHandler(_:) Asynchronous

    POST /api/v3/fez/ID/cancel

    Cancel a FriendlyFez. Owner only. Cancelling a Fez is different from deleting it. A canceled fez is still visible; members may still post to it. But, a cenceled fez does not show up in searches for open fezzes, and should be clearly marked in UI to indicate that it’s been canceled.

    Throws

    403 error if user is not the fez owner. A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func cancelHandler(_ req: Request) async throws -> FezData

    Parameters

    fezID

    in URL path.

    Return Value

    FezData with the updated fez info.

    Show on GitHub
  • fezDeleteHandler(_:) Asynchronous

    POST /api/v3/fez/ID/delete DELETE /api/v3/fez/ID

    Delete the specified FriendlyFez. This soft-deletes the fez. Posts are left as-is.

    To delete, the user must have an access level allowing them to delete the fez. Currently this means moderators and above. The owner of a fez may Cancel the fez, which tells the members the fez was cancelled, but does not delete it. However, a Personal Event can be deleted by its creator, as that LFG type doesn’t allow participants to be added to it.

    Throws

    403 error if the user is not permitted to delete.

    Declaration

    Swift

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

    Parameters

    fezID

    in URL path.

    Return Value

    204 No Content on success.

    Show on GitHub
  • updateHandler(_:) Asynchronous

    POST /api/v3/fez/ID/update

    Update the specified FriendlyFez with the supplied data. Updating a cancelled fez will un-cancel it. Does not process the initialUsers field; use the user add/remove routes to change the participants.

    Note

    All fields in the supplied FezContentData must be filled, just as if the fez were being created from scratch. If there is demand, using a set of more efficient endpoints instead of this single monolith can be considered.

    Throws

    400 error if the data is not valid. 403 error if user is not fez owner. A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func updateHandler(_ req: Request) async throws -> FezData

    Parameters

    fezID

    in URL path.
    requestBody

    FezContentData payload in the HTTP body.

    Return Value

    FezData containing the updated fez info.

    Show on GitHub
  • userAddHandler(_:) Asynchronous

    POST /api/v3/fez/ID/user/ID/add

    Add the specified User to the specified LFG or open chat. This lets the owner invite others.

    Throws

    400 error if user is already in barrel. 403 error if requester is not fez owner. A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func userAddHandler(_ req: Request) async throws -> FezData

    Parameters

    fezID

    in URL path.
    userID

    in URL path.

    Return Value

    FezData containing the updated fez info.

    Show on GitHub
  • userRemoveHandler(_:) Asynchronous

    POST /api/v3/fez/:fezID/user/:userID/remove

    Remove the specified User from the specified FriendlyFez. This lets a fez owner remove others.

    Throws

    400 error if user is not in the barrel. 403 error if requester is not fez owner. A 5xx response should be reported as a likely bug, please and thank you.

    Declaration

    Swift

    func userRemoveHandler(_ req: Request) async throws -> FezData

    Parameters

    fezID

    in URL path.
    userID

    in URL path.

    Return Value

    FezData containing the updated fez info.

    Show on GitHub
  • reportFezHandler(_:) Asynchronous

    POST /api/v3/fez/ID/report

    Creates a Report regarding the specified Fez. This reports on the Fez itself, not any of its posts in particular. This could mean a Fez with reportable content in its Title, Info, or Location fields, or a bunch of reportable posts in the fez.

    Note

    The accompanying report message is optional on the part of the submitting user, but the ReportData is mandatory in order to allow one. If there is no message, send an empty string in the .message field.

    Declaration

    Swift

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

    Parameters

    fezID

    in URL path, the Fez ID to report.
    requestBody

    Return Value

    201 Created on success.

    Show on GitHub

Socket Functions

  • createFezSocket(_:_:) Asynchronous

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

    Opens a websocket to receive updates on the given fez. At the moment there’s only 2 messages that the client may receive:

    • SocketFezPostData - sent when a post is added to the fez.
    • SocketMemberChangeData - sent when a member joins/leaves the fez.

    Note that there’s a bunch of other state change that can happen with a fez; I haven’t built out code to send socket updates for them. The socket returned by this call is only intended for receiving updates; there are no client-initiated messages defined for this socket. Posting messages, leaving the fez, updating or canceling the fez and any other state changes should be performed using the various POST methods of this controller.

    The server validates membership before sending out each socket message, but be sure to close the socket if the user leaves the fez. This method is designed to provide updates only while a user is viewing the fez in your app–don’t open one of these sockets for each fez a user joins and keep them open continually. Use WS /api/v3/notification/socket for long-term status updates.

    Declaration

    Swift

    func createFezSocket(_ req: Request, _ ws: WebSocket) async
    Show on GitHub

  • Declaration

    Swift

    func forwardPostToSockets(_ fez: FriendlyFez, _ post: FezPost, on req: Request) async throws
    Show on GitHub

  • Declaration

    Swift

    func forwardMembershipChangeToSockets(_ fez: FriendlyFez, participantID: UUID, joined: Bool, on req: Request) async throws
    Show on GitHub
  • muteAddHandler(_:) Asynchronous

    POST /api/v3/fez/:fez_ID/mute

    Mute the specified Fez for the current user.

    Declaration

    Swift

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

    Parameters

    fez_ID

    In the URL path.

    Return Value

    201 Created on success; 200 OK if already muted.

    Show on GitHub
  • muteRemoveHandler(_:) Asynchronous

    POST /api/v3/fez/:fez_ID/mute/remove DELETE /api/v3/fez/:fez_ID/mute

    Unmute the specified Fez for the current user.

    Throws

    400 error if the forum was not muted.

    Declaration

    Swift

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

    Parameters

    fez_ID

    In the URL path.

    Return Value

    204 No Content on success; 200 OK if already not muted.

    Show on GitHub

Helper Functions