### Usage example: list users and create admin Source: https://github.com/achtungsoftware/alarik Shows two example HTTP requests: a GET to list all users with pagination, and a POST to create an admin user with isAdmin set to true. All handlers throw Vapor Abort on error (JSON). ```swift // list all users (admin) GET /api/v1/admin/users?page=1&per=25 // create an admin POST /api/v1/admin/users { "name": "Admin", "username": "admin", "password": "secret", "isAdmin": true } ``` -------------------------------- ### Usage example for registration, login, and token usage Source: https://github.com/achtungsoftware/alarik Shows how to register an account (only when ALLOW_ACCOUNT_CREATION=true), log in to get a JWT token, and use the token as a Bearer header for subsequent console calls. ```swift // register an account (only when ALLOW_ACCOUNT_CREATION=true) POST /api/v1/users {"name": "Ada", "username": "ada", "password": "secret"} // log in POST /api/v1/users/login {"username": "ada", "password": "secret"} → {"token": ""} // use the token as a Bearer header for subsequent console calls Authorization: Bearer ``` -------------------------------- ### Run server by hand Source: https://github.com/achtungsoftware/alarik/blob/master/CLAUDE.md Start the Alarik server manually. The process resolves Storage/ relative to its cwd, so run it from a scratch directory to get clean state. ```bash cd alarik && JWT=test-secret ./.build/debug/Alarik serve --hostname 127.0.0.1 --port 8080 ``` -------------------------------- ### End-to-end test suites Source: https://github.com/achtungsoftware/alarik/blob/master/CLAUDE.md Run the end-to-end test suites from the repo root. Each needs a swift build first and port 8080 free. run_all_tests.sh starts each S3 suite against a freshly built binary in a temp state dir, so it never touches the repo's Storage/. Preflight requires swift, aws, rclone, mc, and jq. ```bash ./run_all_tests.sh # everything, ~20 min: unit + aws + rclone + mc + replication + cluster ``` ```bash bash aws_cli_tests.sh # needs a server already running on :8080 ``` ```bash ./replication_tests.sh # starts its own 2 instances (:8081/:8082) ``` ```bash ./cluster_tests.sh # starts its own 4 instances (:8091+), k=2/m=2 ``` -------------------------------- ### Usage example for bucket and shared link endpoints Source: https://github.com/achtungsoftware/alarik Shows example HTTP requests: create a bucket with versioning, list objects under a folder, and create a 1-hour shared link. Errors are Vapor Abort (JSON) — see errors.md. ```sh # create a bucket with versioning POST /api/v1/buckets {"name":"example","versioningEnabled":true} # list objects under a folder GET "/api/v1/objects?bucket=example&prefix=docs/&per=100" # create a 1-hour shared link POST /api/v1/objects/share {"bucket":"example","key":"docs/a.pdf","expiresInSeconds":3600} ``` -------------------------------- ### Swift build and test commands Source: https://github.com/achtungsoftware/alarik/blob/master/CLAUDE.md Build the Swift package and run the unit test suite. Always pass --no-parallel because tests share on-disk state process-wide. Requires isa-l (brew install isa-l on macOS, libisal-dev on Debian). ```bash swift build # debug build -> .build/debug/Alarik ``` ```bash swift test --no-parallel # full unit suite (same as ./test.sh) ``` ```bash swift test --no-parallel --filter "S3ControllerTests" # single suite ``` -------------------------------- ### Create provider usage example Source: https://github.com/achtungsoftware/alarik Example HTTP request to create an OIDC provider. Returns 400 on invalid payload or blocked issuer, 404 on unknown provider id. ```sh # create a provider POST /api/v1/admin/oidcProviders { "name": "GitHub", "issuerURL": "https://github.com", "clientId": "x", "clientSecret": "y", "enabled": true } ``` -------------------------------- ### handleVersions handler signature Source: https://github.com/achtungsoftware/alarik Handles GET /internal/cluster/listing/versions. Requires bucket query parameter. Returns JSON VersionsPageResponse. ```swift @Sendable func handleVersions(req: Request) async throws -> Response ``` -------------------------------- ### GET /api/v1/objects/versions?bucket=&key= Source: https://github.com/achtungsoftware/alarik Lists all versions of an object. Returns an array of ObjectMeta.ResponseDTO. ```APIDOC ## GET /api/v1/objects/versions?bucket=&key= ### Description Lists all versions of an object. Returns an array of ObjectMeta.ResponseDTO. ### Method GET ### Endpoint /api/v1/objects/versions?bucket=&key= ### Parameters #### Query Parameters - **bucket** (string) - Required - Bucket name - **key** (string) - Required - Object key ### Response #### Success Response (200) - **array of ObjectMeta.ResponseDTO** - List of object versions ``` -------------------------------- ### GET /readyz Source: https://github.com/achtungsoftware/alarik Health probe endpoint that returns a 200 status with body "ready" when the service is ready, or a 503 with body "not ready: " until membership is bootstrapped and caches loaded. It is unauthenticated and can be called with GET or HEAD. ```APIDOC ## [GET] /readyz ### Description Health probe endpoint that returns a 200 status with body "ready" when the service is ready, or a 503 with body "not ready: " until membership is bootstrapped and caches loaded. It is unauthenticated and can be called with GET or HEAD. ### Method GET ### Endpoint /readyz ### Response #### Success Response (200) - Body: `"ready"` #### Error Response (503) - Body: `"not ready: "` ``` -------------------------------- ### Kubernetes readinessProbe/livenessProbe example Source: https://github.com/achtungsoftware/alarik Kubernetes probe configuration for the health endpoints. Uses httpGet on /livez and /readyz with initialDelaySeconds 3 and periodSeconds 10. ```yaml livenessProbe: httpGet: { path: /livez, port: 8080 } initialDelaySeconds: 3 periodSeconds: 10 readinessProbe: httpGet: { path: /readyz, port: 8080 } initialDelaySeconds: 3 periodSeconds: 10 ``` -------------------------------- ### Browser flow usage example Source: https://github.com/achtungsoftware/alarik Shows the sequence of HTTP requests for the OIDC login flow: fetch providers, initiate login, receive callback, and final redirect with token. ```text 1. GET /api/v1/auth/oidc/providers → pick provider id 2. GET /api/v1/auth/oidc/login/ → 302 to IdP (sets oidc_state cookie) 3. IdP redirects to /api/v1/auth/oidc/callback?code=…&state=… 4. Callback redirects to /auth/oidc/complete#token= ``` -------------------------------- ### Watch cluster formation with kubectl rollout status Source: https://github.com/achtungsoftware/alarik/blob/master/charts/alarik/templates/NOTES.txt Waits for the StatefulSet rollout to complete. Pods start in order and become Ready only after discovering peers and loading caches; the Service keeps traffic away until then. ```bash kubectl --namespace {{ .Release.Namespace }} rollout status statefulset/{{ include "alarik.fullname" . }} ``` -------------------------------- ### GET / Source: https://github.com/achtungsoftware/alarik Lists all buckets owned by the authenticated user. Returns an XML ListAllMyBucketsResult. ```APIDOC ## GET / ### Description Lists all buckets owned by the authenticated user. ### Method GET ### Endpoint / ### Response #### Success Response (200) - XML `` ``` -------------------------------- ### GET /api/v1/admin/systemStats Source: https://github.com/achtungsoftware/alarik Returns system statistics (admin only). ```APIDOC ## GET /api/v1/admin/systemStats ### Description Returns system statistics (admin only). ### Method GET ### Endpoint /api/v1/admin/systemStats ### Response #### Success Response (200) - **metrics** (object) - System metrics - **accessKeyCount** (integer) - Number of access keys - **sharedLinkCount** (integer) - Number of shared links - **oidcProviderCount** (integer) - Number of OIDC providers - **multipartUploadCount** (integer) - Number of multipart uploads - **clusterNode** (object) - Cluster node information ``` -------------------------------- ### GET /api/v1/admin/buckets Source: https://github.com/achtungsoftware/alarik Lists all buckets (admin only). Returns paginated AdminBucketDTO. ```APIDOC ## GET /api/v1/admin/buckets ### Description Lists all buckets (admin only). Returns paginated AdminBucketDTO. ### Method GET ### Endpoint /api/v1/admin/buckets ### Parameters #### Query Parameters - **page** (integer) - Optional - Page number for pagination - **per** (integer) - Optional - Number of items per page ### Response #### Success Response (200) - **AdminBucketDTO** (array) - List of buckets ``` -------------------------------- ### GET /:bucketName/*key?uploadId=X Source: https://github.com/achtungsoftware/alarik Lists parts of a multipart upload. ```APIDOC ## [GET] /:bucketName/*key?uploadId=X ### Description Lists parts of a multipart upload. ### Method GET ### Endpoint /:bucketName/*key?uploadId=X ### Parameters #### Query Parameters - **uploadId** (string) - Required - The upload ID - **max-parts** - Optional - Maximum number of parts to return - **part-number-marker** - Optional - Part number marker for pagination ### Response #### Success Response (200) - **XML** - List of parts ``` -------------------------------- ### Get admin password from secret Source: https://github.com/achtungsoftware/alarik/blob/master/charts/alarik/templates/NOTES.txt Retrieves the admin password from the Kubernetes secret and decodes it from base64. ```bash kubectl --namespace {{ .Release.Namespace }} get secret {{ include "alarik.secretName" . }} -o jsonpath='{.data.ADMIN_PASSWORD}' | base64 -d ``` -------------------------------- ### GET /api/v1/admin/cluster/placement?bucket=&prefix=&nodeId=&page=&per= Source: https://github.com/achtungsoftware/alarik Retrieves placement entries with optional filters. Returns a paginated list of PlacementEntryDTO. ```APIDOC ## GET /api/v1/admin/cluster/placement?bucket=&prefix=&nodeId=&page=&per= ### Description Retrieves placement entries with optional filters. Returns a paginated list of PlacementEntryDTO. ### Method GET ### Endpoint /api/v1/admin/cluster/placement?bucket=&prefix=&nodeId=&page=&per= ### Parameters #### Query Parameters - **bucket** (string) - Optional - Bucket name filter - **prefix** (string) - Optional - Prefix filter - **nodeId** (string) - Optional - Node ID filter - **page** (integer) - Optional - Page number - **per** (integer) - Optional - Items per page ### Response #### Success Response (200) - **paginated PlacementEntryDTO** - Paginated list of placement entries ``` -------------------------------- ### curl usage for livez and readyz Source: https://github.com/achtungsoftware/alarik Example curl commands to probe the endpoints. livez returns "ok" (200), readyz returns "ready" (200) or "not ready: ..." (503). ```sh curl -s http://localhost:8080/livez # "ok" (200) curl -s http://localhost:8080/readyz # "ready" (200) or "not ready: ..." (503) ``` -------------------------------- ### GET /readyz Source: https://github.com/achtungsoftware/alarik Readiness probe that returns HTTP 200 with body 'ready' when the node is ready to serve traffic, or HTTP 503 with body 'not ready: ' while bootstrapping or caches are not loaded. Used by orchestrators to keep traffic away from nodes that are not ready. ```APIDOC ## [GET] /readyz ### Description Readiness probe that returns HTTP 200 with body 'ready' when the node is ready to serve traffic, or HTTP 503 with body 'not ready: ' while bootstrapping or caches are not loaded. Used by orchestrators to keep traffic away from nodes that are not ready. ### Method GET ### Endpoint /readyz ### Response #### Success Response (200) - **body** (string) - "ready" #### Error Response (503) - **body** (string) - "not ready: " where pending gates are human-readable identifiers joined with commas #### Request Example ```sh curl -s http://localhost:8080/readyz ``` #### Response Example ``` ready ``` ``` -------------------------------- ### GET /:bucketName/*key?tagging Source: https://github.com/achtungsoftware/alarik Retrieves the tag-set of an object. ```APIDOC ## [GET] /:bucketName/*key?tagging ### Description Retrieves the tag-set of an object. ### Method GET ### Endpoint /:bucketName/*key?tagging ### Parameters #### Query Parameters - **tagging** - Required - Indicates this is a tagging operation ### Response #### Success Response (200) - **XML** - Tag-set information ``` -------------------------------- ### HEAD /readyz Source: https://github.com/achtungsoftware/alarik HEAD variant of the readiness probe, returning the same status code as GET but without a response body. Useful for tooling that defaults to HEAD requests. ```APIDOC ## [HEAD] /readyz ### Description HEAD variant of the readiness probe, returning the same status code as GET but without a response body. Useful for tooling that defaults to HEAD requests. ### Method HEAD ### Endpoint /readyz ### Response #### Success Response (200) - **body** (string) - "ready" (omitted in HEAD response) #### Error Response (503) - **body** (string) - "not ready: " (omitted in HEAD response) ``` -------------------------------- ### GET /api/v1/admin/buckets Source: https://github.com/achtungsoftware/alarik Retrieves a paginated list of all buckets with their owning user and raw policy information. ```APIDOC ## [GET] /api/v1/admin/buckets ### Description Retrieves a paginated list of all buckets with their owning user and raw policy information. ### Method GET ### Endpoint /api/v1/admin/buckets ### Parameters #### Query Parameters - **page** (integer) - Optional - Page number for pagination - **per** (integer) - Optional - Number of items per page ### Response #### Success Response (200) Returns a paginated list of buckets (`Page`) with fields: - **id** (UUID?) - Bucket identifier - **name** (string) - Bucket name - **creationDate** (Date?) - Creation date - **versioningStatus** (string) - Versioning status - **user** (User.ResponseDTO?) - Owning user - **policy** (string?) - Raw bucket policy ``` -------------------------------- ### handleObjects handler signature Source: https://github.com/achtungsoftware/alarik Handles GET /internal/cluster/listing/objects. Requires bucket query parameter, prefix defaults to "", maxKeys defaults to 1000. Returns JSON ObjectsPageResponse. ```swift @Sendable func handleObjects(req: Request) async throws -> Response ``` -------------------------------- ### GET /:bucketName?versions Source: https://github.com/achtungsoftware/alarik Lists object versions in a bucket. Returns XML ListVersionsResult. Supports parameters: prefix, delimiter, key-marker, version-id-marker, max-keys. ```APIDOC ## GET /:bucketName?versions ### Description Lists object versions in a bucket. ### Method GET ### Endpoint /:bucketName?versions ### Parameters #### Path Parameters - **bucketName** (string) - Required - The name of the bucket. #### Query Parameters - **versions** (string) - Required - The subresource identifier. - **prefix** (string) - Optional - Limits the response to keys that begin with the specified prefix. - **delimiter** (string) - Optional - A delimiter to group keys. - **key-marker** (string) - Optional - Specifies the key to start with when listing versions. - **version-id-marker** (string) - Optional - Specifies the version ID to start with. - **max-keys** (integer) - Optional - The maximum number of keys returned. ### Response #### Success Response (200) - XML `` ``` -------------------------------- ### handleUploads handler signature Source: https://github.com/achtungsoftware/alarik Handles GET /internal/cluster/listing/uploads. Requires bucket query parameter, prefix defaults to "", maxUploads defaults to 1000. Returns JSON UploadsPageResponse. ```swift @Sendable func handleUploads(req: Request) async throws -> Response ``` -------------------------------- ### GET /api/v1/users/accessKeys Source: https://github.com/achtungsoftware/alarik Lists access keys for the authenticated user. Returns paginated AccessKey.ResponseDTO. ```APIDOC ## GET /api/v1/users/accessKeys ### Description Lists access keys for the authenticated user. Returns paginated AccessKey.ResponseDTO. ### Method GET ### Endpoint /api/v1/users/accessKeys ### Parameters #### Query Parameters - **page** (integer) - Optional - Page number for pagination - **per** (integer) - Optional - Number of items per page ### Response #### Success Response (200) - **AccessKey.ResponseDTO** (array) - List of access keys ``` -------------------------------- ### handleExists method signature Source: https://github.com/achtungsoftware/alarik Handles GET /internal/cluster/objects/exists. Query params: bucket, key, versionId. Header-only existence probe that resolves the path and returns 200/404 without streaming payload. A live delete marker counts as not found. ```swift @Sendable func handleExists(req: Request) async throws -> HTTPStatus ``` -------------------------------- ### GET /api/v1/admin/oidcProviders Source: https://github.com/achtungsoftware/alarik Lists OIDC identity providers in a paginated format, newest first. Requires admin authentication. The response omits the clientSecret field as it is write-only. ```APIDOC ## [GET] /api/v1/admin/oidcProviders ### Description Paginated providers, newest first. `OIDCProvider.ResponseDTO` omits `clientSecret` (write-only). ### Method GET ### Endpoint /api/v1/admin/oidcProviders ### Authentication admin ### Response #### Success Response (200) - **Page** - Paginated list of OIDC providers ``` -------------------------------- ### GET /api/v1/admin/systemStats Source: https://github.com/achtungsoftware/alarik Retrieves live system metrics and counts of access keys, shared links, OIDC providers, and multipart uploads. Includes cluster node identity when in cluster mode. ```APIDOC ## [GET] /api/v1/admin/systemStats ### Description Retrieves live system metrics and counts of access keys, shared links, OIDC providers, and multipart uploads. Includes cluster node identity when in cluster mode. ### Method GET ### Endpoint /api/v1/admin/systemStats ### Response #### Success Response (200) Returns `SystemStats` object with fields: - **metrics** (MetricsCollector.Snapshot) - System metrics including uptime, CPU, memory, and load averages - **accessKeyCount** (Int) - Number of access keys - **sharedLinkCount** (Int) - Number of shared links - **oidcProviderCount** (Int) - Number of OIDC providers - **multipartUploadCount** (Int) - Number of multipart uploads - **clusterNode** (ClusterNodeIdentityDTO?) - Cluster node identity (nil when not in cluster mode) ``` -------------------------------- ### GET /:bucketName?uploads Source: https://github.com/achtungsoftware/alarik Lists in-progress multipart uploads. Returns XML ListMultipartUploadsResult. Supports parameters: prefix, key-marker, upload-id-marker, max-uploads. ```APIDOC ## GET /:bucketName?uploads ### Description Lists in-progress multipart uploads. ### Method GET ### Endpoint /:bucketName?uploads ### Parameters #### Path Parameters - **bucketName** (string) - Required - The name of the bucket. #### Query Parameters - **uploads** (string) - Required - The subresource identifier. - **prefix** (string) - Optional - Limits the response to keys that begin with the specified prefix. - **key-marker** (string) - Optional - Specifies the key to start with when listing uploads. - **upload-id-marker** (string) - Optional - Specifies the upload ID to start with. - **max-uploads** (integer) - Optional - The maximum number of uploads returned. ### Response #### Success Response (200) - XML `` ``` -------------------------------- ### GET /:bucketName Source: https://github.com/achtungsoftware/alarik Lists objects in a bucket (ListObjects/ListObjectsV2). Supports parameters: prefix, delimiter, max-keys, marker, continuation-token, start-after, list-type. ```APIDOC ## GET /:bucketName ### Description Lists objects in a bucket (ListObjects/ListObjectsV2). ### Method GET ### Endpoint /:bucketName ### Parameters #### Path Parameters - **bucketName** (string) - Required - The name of the bucket. #### Query Parameters - **prefix** (string) - Optional - Limits the response to keys that begin with the specified prefix. - **delimiter** (string) - Optional - A delimiter to group keys. - **max-keys** (integer) - Optional - The maximum number of keys returned. - **marker** (string) - Optional - Specifies the key to start with when listing objects. - **continuation-token** (string) - Optional - Used to continue a previous list operation. - **start-after** (string) - Optional - Specifies the key to start after when listing objects. - **list-type** (string) - Optional - Specifies the list type (e.g., 2 for ListObjectsV2). ### Response #### Success Response (200) - XML body ``` -------------------------------- ### GET /api/v1/objects?bucket=&prefix=&delimiter=&search=&page=&per= Source: https://github.com/achtungsoftware/alarik Lists objects in a bucket with optional filters. Returns a paginated list of object metadata response DTOs. ```APIDOC ## GET /api/v1/objects?bucket=&prefix=&delimiter=&search=&page=&per= ### Description Lists objects in a bucket with optional filters. Returns a paginated list of object metadata response DTOs. ### Method GET ### Endpoint /api/v1/objects?bucket=&prefix=&delimiter=&search=&page=&per= ### Parameters #### Query Parameters - **bucket** (string) - Required - Bucket name - **prefix** (string) - Optional - Prefix filter - **delimiter** (string) - Optional - Delimiter for grouping - **search** (string) - Optional - Search filter - **page** (integer) - Optional - Page number - **per** (integer) - Optional - Items per page ### Response #### Success Response (200) - **paginated ObjectMeta.ResponseDTO** - Paginated list of object metadata response DTOs ``` -------------------------------- ### handleHasObjects handler signature Source: https://github.com/achtungsoftware/alarik Handles GET /internal/cluster/listing/has-objects. Requires bucket query parameter. Returns JSON HasObjectsResponse from ObjectFileHandler.hasBucketObjects. ```swift @Sendable func handleHasObjects(req: Request) async throws -> Response ``` -------------------------------- ### GET /api/v1/admin/storageStats Source: https://github.com/achtungsoftware/alarik Retrieves disk storage statistics including total, available, and used bytes, along with bucket and user counts. ```APIDOC ## [GET] /api/v1/admin/storageStats ### Description Retrieves disk storage statistics including total, available, and used bytes, along with bucket and user counts. ### Method GET ### Endpoint /api/v1/admin/storageStats ### Response #### Success Response (200) Returns `StorageStats` object with fields: - **totalBytes** (Int64) - Total disk space - **availableBytes** (Int64) - Available disk space - **usedBytes** (Int64) - Used disk space - **alarikUsedBytes** (Int64) - Disk space used by Alarik - **bucketCount** (Int) - Number of buckets - **userCount** (Int) - Number of users ``` -------------------------------- ### GET /api/v1/accessKeyGenerator Source: https://github.com/achtungsoftware/alarik Returns freshly generated S3 credentials for client-side creation. The handler can be used to let the console pre-generate credentials for a new S3 access key without the client ever seeing the secret derivations. ```APIDOC ## [GET] /api/v1/accessKeyGenerator ### Description Returns freshly generated S3 credentials for client-side creation. The handler can be used to let the console pre-generate credentials for a new S3 access key without the client ever seeing the secret derivations. ### Method GET ### Endpoint /api/v1/accessKeyGenerator ### Authentication Requires `InternalAuthenticator` (JWT Bearer or X-Access-Key / X-Secret-Key) ### Response #### Success Response (200) - **accessKeyId** (String) - 20 chars from `A-Z0-9` (`S3KeyGenerator.generateAccessKeyId`) - **secretAccessKey** (String) - 40-char base64 of 30 random bytes (`S3KeyGenerator.generateSecretAccessKey`) - **createdAt** (Date) - Time of generation #### Request Example ```sh # authenticated (JWT Bearer or X-Access-Key / X-Secret-Key) curl -H "Authorization: Bearer " \ http://localhost:8080/api/v1/accessKeyGenerator ``` #### Response Example ```json {"accessKeyId":"AKIAIOSFODNN7EXAMPLE","secretAccessKey":"...","createdAt":"..."} ``` #### Error Responses - **401** - Missing or invalid Authorization - **403** - Valid token naming a deleted user ``` -------------------------------- ### handleLatestVersion method signature Source: https://github.com/achtungsoftware/alarik Handles GET /internal/cluster/objects/latest-version. Query params: bucket, key. Resolves the latest version id from this node's local .latest pointer. Returns 200 with version id, or 204 when the key is unversioned/absent. ```swift @Sendable func handleLatestVersion(req: Request) async throws -> Response ``` -------------------------------- ### GET /api/v1/auth/oidc/callback Source: https://github.com/achtungsoftware/alarik Completes the OIDC flow. Redirects to the console base URL with a token or error fragment. ```APIDOC ## GET /api/v1/auth/oidc/callback ### Description Completes the OIDC flow. Redirects to the console base URL with a token or error fragment. ### Method GET ### Endpoint /api/v1/auth/oidc/callback ### Response #### Success Response (302) - **Location** (string) - Redirect URL with token fragment #### Error Response (302) - **Location** (string) - Redirect URL with error fragment ``` -------------------------------- ### GET /api/v1/buckets?search= Source: https://github.com/achtungsoftware/alarik Lists buckets with optional search filter. Returns a paginated list of bucket response DTOs. ```APIDOC ## GET /api/v1/buckets?search= ### Description Lists buckets with optional search filter. Returns a paginated list of bucket response DTOs. ### Method GET ### Endpoint /api/v1/buckets?search= ### Parameters #### Query Parameters - **search** (string) - Optional - Search filter for bucket names ### Response #### Success Response (200) - **paginated Bucket.ResponseDTO** - Paginated list of bucket response DTOs ``` -------------------------------- ### handleList signature Source: https://github.com/achtungsoftware/alarik Handler for GET /internal/cluster/metadata/list. Takes collection query parameter. Returns only this node's local contribution as JSON array of WireEntry with listingCompleteHeader. ```swift @Sendable func handleList(req: Request) async throws -> Response ``` -------------------------------- ### GET /api/v1/admin/buckets/:bucketName/policy Source: https://github.com/achtungsoftware/alarik Gets the policy of a bucket (admin only). Returns JSON with PolicyDTO. ```APIDOC ## GET /api/v1/admin/buckets/:bucketName/policy ### Description Gets the policy of a bucket (admin only). Returns JSON with PolicyDTO. ### Method GET ### Endpoint /api/v1/admin/buckets/:bucketName/policy ### Parameters #### Path Parameters - **bucketName** (string) - Required - Name of the bucket ### Response #### Success Response (200) - **policy** (object) - Bucket policy ``` -------------------------------- ### handleOwnedStats handler signature Source: https://github.com/achtungsoftware/alarik Handles GET /internal/cluster/listing/owned-stats. Requires bucket query parameter, prefix defaults to "". Requires cluster mode (ClusterConfigurationKey present, else 503). Returns OwnedStatsResponse. ```swift @Sendable func handleOwnedStats(req: Request) async throws -> Response ``` -------------------------------- ### SharedLinkController serve method signature Source: https://github.com/achtungsoftware/alarik Defines the serve method that handles GET /api/v1/shared/:token. It parses the token as a UUID, loads the SharedLink, checks expiry, resolves placement, and serves or forwards the object. Returns 404 for invalid, expired, or missing objects to avoid leaking information to unauthenticated callers. ```swift @Sendable func serve(req: Request) async throws -> Response ``` -------------------------------- ### GET /livez Source: https://github.com/achtungsoftware/alarik Health probe endpoint that returns a 200 status with body "ok" when the process is up. It is unauthenticated and can be called with GET or HEAD. ```APIDOC ## [GET] /livez ### Description Health probe endpoint that returns a 200 status with body "ok" when the process is up. It is unauthenticated and can be called with GET or HEAD. ### Method GET ### Endpoint /livez ### Response #### Success Response (200) - Body: `"ok"` ``` -------------------------------- ### GET /api/v1/users/accessKeys Source: https://github.com/achtungsoftware/alarik Lists the authenticated user's access keys, newest first, paginated. Requires InternalAuthenticator authentication. ```APIDOC ## [GET] /api/v1/users/accessKeys ### Description Lists the authenticated user's access keys, newest first, paginated. Requires InternalAuthenticator authentication. ### Method GET ### Endpoint /api/v1/users/accessKeys ### Authentication - **InternalAuthenticator** - Required ### Response #### Success Response (200) - **Page** - Paginated list of the user's access keys ``` -------------------------------- ### curl request to accessKeyGenerator endpoint Source: https://github.com/achtungsoftware/alarik Shows an authenticated curl request to generate S3 credentials, with example JSON response. ```sh # authenticated (JWT Bearer or X-Access-Key / X-Secret-Key) curl -H "Authorization: Bearer " \ http://localhost:8080/api/v1/accessKeyGenerator # {"accessKeyId":"AKIAIOSFODNN7EXAMPLE","secretAccessKey":"...","createdAt":"..."} ``` -------------------------------- ### GET /livez Source: https://github.com/achtungsoftware/alarik Liveness probe that returns HTTP 200 with body 'ok' when the process is serving. It does not consult cluster health and is intended for orchestrators to verify the node is alive. ```APIDOC ## [GET] /livez ### Description Liveness probe that returns HTTP 200 with body 'ok' when the process is serving. It does not consult cluster health and is intended for orchestrators to verify the node is alive. ### Method GET ### Endpoint /livez ### Response #### Success Response (200) - **body** (string) - "ok" #### Request Example ```sh curl -s http://localhost:8080/livez ``` #### Response Example ``` ok ``` ``` -------------------------------- ### Scale up StatefulSet Source: https://github.com/achtungsoftware/alarik/blob/master/charts/alarik/templates/NOTES.txt Scales the StatefulSet up. Safe at any time; new pods join and existing nodes migrate a share of data onto them automatically. ```bash kubectl --namespace {{ .Release.Namespace }} scale statefulset {{ include "alarik.fullname" . }} --replicas=N ``` -------------------------------- ### Scale down StatefulSet with scale-down.sh Source: https://github.com/achtungsoftware/alarik/blob/master/charts/alarik/templates/NOTES.txt Scales down using the provided script, not kubectl scale. The script drains each pod first so its data moves to remaining nodes before removal; removing a pod outright leaves shards missing until a manual resync. ```bash ./scale-down.sh {{ include "alarik.fullname" . }} N {{ .Release.Namespace }} ``` -------------------------------- ### GET /api/v1/admin/storageStats Source: https://github.com/achtungsoftware/alarik Returns storage statistics (admin only). ```APIDOC ## GET /api/v1/admin/storageStats ### Description Returns storage statistics (admin only). ### Method GET ### Endpoint /api/v1/admin/storageStats ### Response #### Success Response (200) - **totalBytes** (integer) - Total storage bytes - **availableBytes** (integer) - Available storage bytes - **usedBytes** (integer) - Used storage bytes - **alarikUsedBytes** (integer) - Alarik used storage bytes - **bucketCount** (integer) - Number of buckets - **userCount** (integer) - Number of users ``` -------------------------------- ### GET /api/v1/admin/cluster/erasure-coding/status Source: https://github.com/achtungsoftware/alarik Retrieves the erasure coding status. Returns an ErasureCodingStatusDTO. ```APIDOC ## GET /api/v1/admin/cluster/erasure-coding/status ### Description Retrieves the erasure coding status. Returns an ErasureCodingStatusDTO. ### Method GET ### Endpoint /api/v1/admin/cluster/erasure-coding/status ### Response #### Success Response (200) - **ErasureCodingStatusDTO** - Object containing erasure coding status ``` -------------------------------- ### GET /api/v1/admin/cluster/nodes Source: https://github.com/achtungsoftware/alarik Lists all cluster nodes. Returns an array of ClusterNodeDTO. ```APIDOC ## GET /api/v1/admin/cluster/nodes ### Description Lists all cluster nodes. Returns an array of ClusterNodeDTO. ### Method GET ### Endpoint /api/v1/admin/cluster/nodes ### Response #### Success Response (200) - **array of ClusterNodeDTO** - List of cluster nodes ``` -------------------------------- ### GET /api/v1/admin/buckets/:bucketName/stats Source: https://github.com/achtungsoftware/alarik Returns statistics for a specific bucket (admin only). ```APIDOC ## GET /api/v1/admin/buckets/:bucketName/stats ### Description Returns statistics for a specific bucket (admin only). ### Method GET ### Endpoint /api/v1/admin/buckets/:bucketName/stats ### Parameters #### Path Parameters - **bucketName** (string) - Required - Name of the bucket ### Response #### Success Response (200) - **sizeBytes** (integer) - Total size of bucket in bytes - **objectCount** (integer) - Number of objects in bucket ``` -------------------------------- ### createProvider handler signature Source: https://github.com/achtungsoftware/alarik Validates/decodes OIDCProvider.Create and rejects blocked/SSRF-risky issuer URLs via OIDCDiscoveryCache.rejectMetadataHost with a 400 before saving. ```swift @Sendable func createProvider(req: Request) async throws -> OIDCProvider.ResponseDTO ``` -------------------------------- ### Write handler signatures (handlePut, handlePutIfAbsent, handleDelete, handleConsumeIfPresent) Source: https://github.com/achtungsoftware/alarik Signatures for the four write handlers. handlePut and handleDelete return .ok. handlePutIfAbsent returns a Response with X-Alarik-Created header. handleConsumeIfPresent returns body or 404. ```swift @Sendable func handlePut(req: Request) async throws -> HTTPStatus // .ok @Sendable func handlePutIfAbsent(req: Request) async throws -> Response // sets X-Alarik-Created: true|false @Sendable func handleDelete(req: Request) async throws -> HTTPStatus // .ok @Sendable func handleConsumeIfPresent(req: Request) async throws -> Response // body, or 404 ``` -------------------------------- ### GET /api/v1/admin/users Source: https://github.com/achtungsoftware/alarik Lists all users (admin only). Returns paginated User.ResponseDTO. ```APIDOC ## GET /api/v1/admin/users ### Description Lists all users (admin only). Returns paginated User.ResponseDTO. ### Method GET ### Endpoint /api/v1/admin/users ### Parameters #### Query Parameters - **page** (integer) - Optional - Page number for pagination - **per** (integer) - Optional - Number of items per page ### Response #### Success Response (200) - **User.ResponseDTO** (array) - List of users ``` -------------------------------- ### handlePush method signature Source: https://github.com/achtungsoftware/alarik Handles POST /internal/cluster/objects/push. Writes the exact version a peer sends without minting a new version id. Reads ObjectMeta from the X-Alarik-Object-Meta header, spools the body to disk, and writes to the path selected by BucketVersioningCache status. Returns .ok on success; Abort(.badRequest) for missing/invalid meta header, Abort(.internalServerError) for spool write failure. ```swift @Sendable func handlePush(req: Request) async throws -> HTTPStatus ``` -------------------------------- ### GET /api/v1/auth/oidc/providers Source: https://github.com/achtungsoftware/alarik Lists enabled OIDC providers. No authentication required. ```APIDOC ## GET /api/v1/auth/oidc/providers ### Description Lists enabled OIDC providers. No authentication required. ### Method GET ### Endpoint /api/v1/auth/oidc/providers ### Response #### Success Response (200) - **OIDCProvider.PublicDTO** (array) - List of enabled providers with id and name ``` -------------------------------- ### Storage and system statistics handler signatures Source: https://github.com/achtungsoftware/alarik Declares getStorageStats (disk totals from BucketHandler.rootPath and counts from MetadataListingService) and getSystemStats (live metrics snapshot plus cheap counts and cluster-node identity when clustered). ```swift @Sendable func getStorageStats(req: Request) async throws -> StorageStats @Sendable func getSystemStats(req: Request) async throws -> SystemStats ``` -------------------------------- ### listProviders handler signature Source: https://github.com/achtungsoftware/alarik Paginated list of OIDC providers, newest first. ResponseDTO omits clientSecret (write-only). ```swift @Sendable func listProviders(req: Request) async throws -> Page ``` -------------------------------- ### createAccessKey handler Source: https://github.com/achtungsoftware/alarik Decodes AccessKey.Create and creates key for authenticated user, populating caches. Duplicate access-key value throws conflict. ```swift @Sendable func createAccessKey(req: Request) async throws -> AccessKey.ResponseDTO ``` -------------------------------- ### GET /api/v1/admin/cluster/storage Source: https://github.com/achtungsoftware/alarik Retrieves storage information for all nodes. Returns an array of NodeStorageDTO. ```APIDOC ## GET /api/v1/admin/cluster/storage ### Description Retrieves storage information for all nodes. Returns an array of NodeStorageDTO. ### Method GET ### Endpoint /api/v1/admin/cluster/storage ### Response #### Success Response (200) - **array of NodeStorageDTO** - List of node storage information - **nodeId** (string) - Node ID - **sizeBytes** (integer) - Total size in bytes - **objectCount** (integer) - Number of objects ``` -------------------------------- ### GET /api/v1/admin/cluster/erasure-coding/tasks Source: https://github.com/achtungsoftware/alarik Retrieves the erasure coding tasks. Returns an array of ErasureCodedTaskDetailDTO. ```APIDOC ## GET /api/v1/admin/cluster/erasure-coding/tasks ### Description Retrieves the erasure coding tasks. Returns an array of ErasureCodedTaskDetailDTO. ### Method GET ### Endpoint /api/v1/admin/cluster/erasure-coding/tasks ### Response #### Success Response (200) - **array of ErasureCodedTaskDetailDTO** - List of erasure coding task details ``` -------------------------------- ### GET /api/v1/objects/share Source: https://github.com/achtungsoftware/alarik Lists all shared links. Returns a paginated list of SharedLink.ResponseDTO. ```APIDOC ## GET /api/v1/objects/share ### Description Lists all shared links. Returns a paginated list of SharedLink.ResponseDTO. ### Method GET ### Endpoint /api/v1/objects/share ### Response #### Success Response (200) - **paginated SharedLink.ResponseDTO** - Paginated list of shared links ``` -------------------------------- ### GET /api/v1/admin/oidcProviders Source: https://github.com/achtungsoftware/alarik Lists all OIDC providers (admin only). Returns paginated OIDCProvider.ResponseDTO. ```APIDOC ## GET /api/v1/admin/oidcProviders ### Description Lists all OIDC providers (admin only). Returns paginated OIDCProvider.ResponseDTO. ### Method GET ### Endpoint /api/v1/admin/oidcProviders ### Parameters #### Query Parameters - **page** (integer) - Optional - Page number for pagination - **per** (integer) - Optional - Number of items per page ### Response #### Success Response (200) - **OIDCProvider.ResponseDTO** (array) - List of OIDC providers ``` -------------------------------- ### listObjectVersions Source: https://github.com/achtungsoftware/alarik Lists versions of an object in a bucket. ```APIDOC ## listObjectVersions ### Description Lists versions of an object in a bucket. ### Method GET ### Endpoint InternalBucketController.listObjectVersions ### Parameters #### Query Parameters - **bucket** (string) - Required - Bucket name - **key** (string) - Required - Object key ### Response #### Success Response (200) - **Response** - List of object versions ``` -------------------------------- ### listObjects Source: https://github.com/achtungsoftware/alarik Lists objects in a bucket, optionally filtered by prefix, delimiter, search, and pagination. Supports cluster-wide listing with folders synthesized via ObjectMeta.ResponseDTO(folderKey:). ```APIDOC ## listObjects ### Description Lists objects in a bucket, optionally filtered by prefix, delimiter, search, and pagination. Supports cluster-wide listing with folders synthesized via ObjectMeta.ResponseDTO(folderKey:). ### Method GET ### Endpoint InternalBucketController.listObjects ### Parameters #### Query Parameters - **bucket** (string) - Required - Bucket name - **prefix** (string) - Optional - Object key prefix - **delimiter** (string) - Optional - Delimiter for folder grouping (default `/`) - **search** (string) - Optional - Search term - **page** (integer) - Optional - Page number - **per** (integer) - Optional - Items per page ### Response #### Success Response (200) - **Page** - Paginated list of object metadata ``` -------------------------------- ### GET /api/v1/admin/cluster/rebalance/tasks Source: https://github.com/achtungsoftware/alarik Retrieves the most-stuck rebalance tasks (up to 200). Returns an array of ReplicationTaskDetailDTO. ```APIDOC ## GET /api/v1/admin/cluster/rebalance/tasks ### Description Retrieves the most-stuck rebalance tasks (up to 200). Returns an array of ReplicationTaskDetailDTO. ### Method GET ### Endpoint /api/v1/admin/cluster/rebalance/tasks ### Response #### Success Response (200) - **array of ReplicationTaskDetailDTO** - List of replication task details (cap 200, most-stuck first) ``` -------------------------------- ### POST /:bucketName/*key?uploads Source: https://github.com/achtungsoftware/alarik Initiates a multipart upload and returns an UploadId. ```APIDOC ## [POST] /:bucketName/*key?uploads ### Description Initiates a multipart upload and returns an UploadId. ### Method POST ### Endpoint /:bucketName/*key?uploads ### Parameters #### Query Parameters - **uploads** - Required - Indicates this is an initiate multipart upload operation ### Response #### Success Response (200) - **XML ** - Contains UploadId ``` -------------------------------- ### GET /api/v1/admin/cluster/rebalance/status Source: https://github.com/achtungsoftware/alarik Retrieves the rebalance status. Returns a RebalanceStatusDTO with pending and failed counts. ```APIDOC ## GET /api/v1/admin/cluster/rebalance/status ### Description Retrieves the rebalance status. Returns a RebalanceStatusDTO with pending and failed counts. ### Method GET ### Endpoint /api/v1/admin/cluster/rebalance/status ### Response #### Success Response (200) - **RebalanceStatusDTO** - Object containing rebalance status - **pendingCount** (integer) - Number of pending tasks - **failedCount** (integer) - Number of failed tasks - **pendingByReason** (object) - Pending tasks grouped by reason - **replicationFactor** (integer) - Replication factor ``` -------------------------------- ### downloadObjects Source: https://github.com/achtungsoftware/alarik Downloads one or more objects. Streams files or packs multiple keys into a ZIP archive. ```APIDOC ## downloadObjects ### Description Downloads one or more objects. Streams files or packs multiple keys into a ZIP archive. ### Method POST ### Endpoint InternalBucketController.downloadObjects ### Parameters #### Request Body - **bucket** (string) - Required - Bucket name - **keys** (array of string) - Required - List of object keys - **versionId** (string) - Optional - Version ID for a specific version ### Response #### Success Response (200) - **Response** - Streamed file or ZIP archive ``` -------------------------------- ### callback method Source: https://github.com/achtungsoftware/alarik Performs token exchange and IdP identity verification, then redirects to /auth/oidc/complete#token= on success or ...#error= on failure. ```swift @Sendable func callback(req: Request) async throws -> Response ```