ClientController

struct ClientController : APIRouteCollection

extension ClientController: FezProtocol

The collection of /api/v3/client/* route endpoints and handler functions that provide bulk retrieval services for registered API clients.

Show on GitHub

RouteCollection Conformance

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

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

tokenAuthGroup Handlers (logged in)

userSearchHandler(_:) Asynchronous
GET /api/v3/client/usersearch

Retrieves all UserProfile.userSearch values, returning an array of precomposed .userSearch strings in UserSearch format. The intended use for this data is to efficiently isolate a particular user in an auto-complete type scenario, using all of the .displayName, .username and .realName profile fields.

Requires
x-swiftarr-user header in the request.

Throws
400 error if no valid date string provided. 401 error if the required header is missing or invalid. 403 error if user is not a registered client.
Declaration
Swift

func userSearchHandler(_ req: Request) async throws -> [UserSearch]
Return Value

An array of UserSearch containing the ID and .userSearch string values of all users, sorted by username.

Show on GitHub


                    
                    
                    userUpdatesHandler(_:)

Asynchronous

GET /api/v3/client/user/updates/since/DATE

Retrieves the UserHeader of all users with a .profileUpdatedAt timestamp later than the specified date. The DATE parameter is a string, and may be provided in either of two formats:

a string literal Double (e.g. “1574364935” or “1574364935.88991”)
an ISO 8601 yyyy-MM-dd'T'HH:mm:ssZ string (e.g. “2019-11-21T05:31:28Z”)

The second format is precisely what is returned in swiftarr JSON responses, while the numeric form makes for a prettier URL.

Requires

x-swiftarr-user header in the request.

Throws

400 error if no valid date string provided. 401 error if the required header is missing or invalid. 403 error if user is not a registered client.

Declaration

Swift

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

Parameters


                                Date

in URL path. See above for formats.

Return Value

An array of UserHeader containing all updated users.

Show on GitHub

prometheusMetricsSource(_:)
GET /api/v3/client/metrics

For use with Prometheus, a server metrics package. When a Prometheus server process is connected, it will poll this endpoint for metrics updates. You can then view Swiftarr metrics data with charts and graphs in a web page served by Prometheus.

Throws
403 error if user is not a registered client.
Declaration
Swift

func prometheusMetricsSource(_ req: Request) -> EventLoopFuture<String>
Return Value

Data about what requests are being called, how long they take to complete, how the databases are doing, what the server’s CPU utilization is, plus a bunch of other metrics data. All the data is in some opaquish Prometheus format.

Show on GitHub
prometheusAlertHandler(_:) Asynchronous
POST /api/v3/client/alert

For use with the Prometheus Alertmanager. A webhook can be configured to POST a payload containing information about actively firing/cleared alerts. A situation arose on JoCo 2022 in which the server ran out of disk space. We have Prometheus metrics for this but no way to tell us about it without checking the dashboards manually. This endpoint translates that payload into a Seamail that can be sent to an arbitrary user (usually TwitarrTeam).

It is expected that the Prometheus alerts are configured with two custom annotations:
- participants: A comma-seperated list of usernames to send the seamail to.
- summary: A string containing a message body to send in the seamail.
This should be used very judiciously and only for actionable alerts! On-call sucks in the real world and I don’t want people to get spammed with messages while on vacation.

Throws
403 error if user is not a registered client.
Declaration
Swift

func prometheusAlertHandler(_ req: Request) async throws -> Response
Return Value

201 created.

Show on GitHub
healthHandler(_:) Asynchronous
GET /api/v3/client/health

HTTP endpoint to report application health status. During the 2022 “Bad Gateway” issue we noticed the app taking a while to start up with a bunch of Users in the table. During this time Traefik would route requests but the app wasn’t listening yet. This healthcheck won’t complete successfully unless the app has started so it’s a good barometer of when we’re ready to service requests.

Throws
500 error if Redis or Postgres are unhappy.
Declaration
Swift

func healthHandler(_ req: Request) async throws -> HealthResponse
Return Value

200 OK.

Show on GitHub