Generated with

com.worxbend.codeberg4s

package com.worxbend.codeberg4s

Members list

Packages

Type members

Classlikes

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: ApiErrorBody.type

A parsed Forgejo error payload.

Forgejo answers a failed request with {"message": ..., "url": ...} and occasionally adds errors: [...]. Every field is optional in practice even where the spec claims otherwise, so decoding an error body never fails: an unparseable payload becomes ApiErrorBody.Empty rather than a second, nested failure.

Value parameters

errors: per-field problems reported by validation endpoints; empty when the server sent none
message: the server-supplied explanation, when present
url: the documentation URL Forgejo points at, when present

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: BaseUri.type

Everything a caller needs to identify one attempted API call after it failed.

A CallContext is attached to every remote failure so that a log line or a bug report identifies the operation without the caller having to reconstruct it.

'''Security contract:''' uri is already redacted by the transport before this value is built. It must never contain a token, a password, or a sudo parameter. Nothing downstream re-derives a URI from the configuration.

Value parameters

durationMs: wall-clock duration of the attempt in milliseconds, measured by the transport
method: the HTTP method that was used
operation: a stable, greppable operation id such as "issues.list", one per endpoint; it never changes, so it is safe to alert on
requestId: the value of the x-request-id response header when the instance supplied one
uri: the request URI, already redacted

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: CodebergConfig.type

Everything a client needs to talk to one Forgejo deployment.

Built once near the client's construction and passed by constructor from there on. Every field naming a domain concept — the base URI, the credentials, the page size, the user agent — is a validated type rather than a raw primitive, so a misconfigured client fails at construction instead of on the first call. The two timeouts and the two response-body bounds are quantities rather than domain concepts and are carried as they are; a negative or zero value is not rejected here, and would make every call fail.

toString is safe to log: the credential types inside auth.Auth redact themselves.

Value parameters

auth: how requests are authenticated
baseUri: the API root; defaults to BaseUri.Codeberg but must be configurable for self-hosted instances
connectTimeout: how long to wait for the connection to be established
defaultPageSize: the page size used when a caller does not supply paging.PageParams
maxDownloadBodyBytes: the same bound for the archive-downloading operations under client.downloads, which is larger for the reason DefaultMaxDownloadBodyBytes gives
maxResponseBodyBytes: the most bytes a textual response may carry before the call fails with TransportCause.ResponseTooLarge; see DefaultMaxResponseBodyBytes
readTimeout: how long to wait for the response once the request has been sent
retry: the retry policy applied to safe methods; see retry.RetryPolicy
userAgent: the User-Agent header sent with every request

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Every failure this library reports, as one closed family.

Recoverable failures are values: no operation throws for a 404, a timeout, or a malformed payload. Each remote case carries a CallContext so a caller can tell which call failed without correlating logs.

Choosing a reaction:

CodebergError.Transport — nothing reached the server; safe to retry a safe method.
CodebergError.Api — the server answered; branch on status.
CodebergError.DecodingFailed — the server answered successfully but the payload did not match the model; retrying will not help, and path plus snippet is what a bug report needs.
CodebergError.Validation — the request was rejected before it was built; fix the argument.
CodebergError.RetriesExhausted — the retry engine gave up; last is the failure that ended it, never discarded.
CodebergError.WalkTruncated — a walk over every page hit its page cap with pages still to come; the answer it would otherwise have returned was incomplete, so it is not returned at all.

Attributes

Companion: object
Supertypes: trait Enum

trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: enum
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: CodebergError.type

The HTTP methods this library issues.

The domain deliberately owns this type rather than borrowing one from a transport library: nothing below the transport adapter should depend on sttp's Method.

Attributes

Supertypes: trait Enum

trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: JsonPath.type

The version string a Forgejo or Codeberg instance reports from GET /version.

Deliberately '''not''' parsed into major/minor/patch. The value captured from the live instance in golden/version/version.json is 16.0.0-dev-668-1bdb1938+gitea-1.22.0: a Forgejo release train, a development distance, a Git hash and a Gitea compatibility claim, in one field with no documented grammar. Any structure this library imposed on it would be a guess, and a guess that silently mis-orders two builds is worse than no ordering at all.

Compare instances for equality, log the value, show it in a bug report — but do not branch on it ordinally. Capability detection belongs on the endpoint that has the capability.

Value parameters

raw: the string exactly as the instance reported it, never blank

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Why a request produced no usable HTTP response.

The transport adapter classifies the exception it caught into one of these cases; anything it cannot classify becomes TransportCause.Unknown rather than being dropped. A status code — including 5xx — is never a transport cause: that is CodebergError.Api.

All but one of these mean nothing arrived at all. TransportCause.ResponseTooLarge is the exception: a response did begin to arrive, and reading it was abandoned once it passed the bound in CodebergConfig. It is here rather than under CodebergError.Api because the status is not what went wrong and the body was never completed, so there is nothing to hand a status-mapping decision.

Each case carries a short detail taken from the underlying exception message. Details are for humans; callers branch on the case, not on the text.

Attributes

Supertypes: trait Enum

trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Supertypes: class Object

trait Matchable

class Any
Self type: UserAgent.type

A single pre-flight validation failure produced by a smart constructor.

Validation happens before any request is built, so a ValidationError never carries a CallContext: there is no call yet. It is lifted into CodebergError.Validation when it has to travel on the same channel as remote failures.

Value parameters

field: the lower-camel-case name of the rejected concept, stable enough to branch on — "owner", "repoName", "apiToken", "baseUri", "pageSize"
message: a short, human-readable reason, lowercase and without a trailing period. It never contains credential material.

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Types

The root of a Forgejo API v1 deployment, for example https://codeberg.org/api/v1.

The base URI is configuration, not a constant: the same client must work against codeberg.org and against any self-hosted Forgejo instance. Values are normalised without a trailing slash so that request building can join segments with a single / and never produce //.

Attributes

A location inside a JSON document, used to say where decoding failed.

The path is built from already-rendered segments, so rendering is a concatenation and the round trip cannot lose the difference between the field "0" and the array index 0.

JsonPath.of("owner", "login").render        // "$.owner.login"
JsonPath.Root.field("items").index(0).render // "$.items[0]"

Values compare structurally, so a decoder test can assert on an expected path.

Attributes

The User-Agent header this client sends.

Forgejo instances use it to attribute traffic, and some deployments reject requests without one, so it is required configuration rather than an option. Control characters are rejected because a \r or \n in a header value is a response-splitting vector.

Attributes

In this article

Generated with