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

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

  • 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) async throws -> [UInt8]

    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

  • 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