FezController Structure Reference

FezURLQueryStruct
See more
Declaration
Swift

struct FezURLQueryStruct : Content
Show on GitHub
registerRoutes(_:)
Required. Registers routes to the incoming router.
Declaration
Swift

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

Retrieving Fezzes

typesHandler(_:)
/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.
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.
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

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`	`PostContentData`

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


                    
                    
                    reportFezPostHandler(_:)

Asynchronous

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.

Note

Eventually, cancelling a fez should notifiy all members via the notifications endpoint.

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.

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.

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/ID/user/:userID/remove

Remove the specified User from the specified FriendlyFez barrel. 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`	`ReportData`

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


                    
                    
                    forwardPostToSockets(_:_:on:)

Declaration

Swift

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

Show on GitHub


                    
                    
                    forwardMembershipChangeToSockets(_:participantID:joined:on:)

Declaration

Swift

func forwardMembershipChangeToSockets(_ fez: FriendlyFez, participantID: UUID, joined: Bool, on req: Request) 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


                    
                    
                    buildFezData(from:with:posts:for:on:)

Declaration

Swift

func buildFezData(
	from fez: FriendlyFez,
	with pivot: FezParticipant? = nil,
	posts: [FezPostData]? = nil,
	for cacheUser: UserCacheData,
	on req: Request
) throws -> FezData

Show on GitHub


                    
                    
                    buildPostsForFez(_:pivot:on:user:)

Asynchronous

Declaration

Swift

func buildPostsForFez(_ fez: FriendlyFez, pivot: FezParticipant?, on req: Request, user: UserCacheData) async throws
	-> ([FezPostData], Paginator)

Show on GitHub


                    
                    
                    getUserPivot(fez:userID:on:)

Asynchronous

Declaration

Swift

func getUserPivot(fez: FriendlyFez, userID: UUID, on db: Database) async throws -> FezParticipant?

Show on GitHub


                    
                    
                    userCanViewMemberData(user:fez:)

Declaration

Swift

func userCanViewMemberData(user: UserCacheData, fez: FriendlyFez) -> Bool

Show on GitHub


                    
                    
                    getEffectiveUser(user:req:)

Declaration

Swift

func getEffectiveUser(user: UserCacheData, req: Request) throws -> UserCacheData

Show on GitHub


                    
                    
                    getEffectiveUser(user:req:fez:)

Declaration

Swift

func getEffectiveUser(user: UserCacheData, req: Request, fez: FriendlyFez) -> UserCacheData

Show on GitHub