Use the direct provider¶

Not every download source is a forge. A tool distributed from a plain web server, an internal artefact store, or a CDN has releases but no API to ask about them. The direct provider covers that case, and ships inside this module because it is the one provider that will never need a vendor SDK.

It is also the reference implementation: it takes the same credential path, uses the same config layout, and runs the same conformance harness a third-party provider should.

import _ "gitlab.com/phpboyscout/go/forge/direct"

Compose the download URL¶

There is no API, so the asset URL is built from a template. Only url_template is required:

direct:
  url_template: "https://dl.example.com/{tool}/{version}/{tool}_{os}_{arch}.{ext}"

Placeholders:

The amd64 → x86_64 substitution matches what GoReleaser and most release pipelines actually publish, rather than what Go calls the architecture.

Tell it how to find the latest version¶

With no API, "what is the latest release?" needs an answer from somewhere. Two options, and configuring neither is an error, because silently assuming a version would be worse:

Pin it. Useful for a fixed internal distribution:

direct:
  pinned_version: "v1.2.3"

Point at a version endpoint. The format is auto-detected from the response's Content-Type; version_format is an override for a server that sends the wrong one, not the only way to select a parser:

direct:
  version_url: "https://dl.example.com/mytool/latest.json"
  version_format: "json"      # OPTIONAL override: json | yaml | xml
  version_key: "tag_name"     # which field holds the version

When version_key is unset (or names a field the document lacks) the parsers fall back to tag_name, then version, in that order.

Responses each format accepts:

# text/plain
v1.2.3

{"tag_name": "v1.2.3", "prerelease": false}

version: v1.2.3

<release><version>v1.2.3</version></release>

Without either, version checks return ErrVersionUnknown, a sentinel that lives in the direct package rather than the shared contract, because it names config keys no forge-backed provider has.

The version endpoint response is capped at 1 MiB.

Checksums and signatures¶

Because there is no asset listing to search, direct composes those URLs too, opting into both optional capability interfaces:

direct:
  checksum_url_template: "https://dl.example.com/{tool}/{version}/checksums.txt"
  signature_url_template: "https://dl.example.com/{tool}/{version}/checksums.txt.sig"

Leave either unset and the provider returns ErrNotSupported for it, so the caller falls back or applies its own policy. Both reads are bounded by the caller-supplied maxBytes.

Recipes¶

A static site or object store¶

direct:
  tool_name:    mytool
  url_template: "https://dl.example.com/mytool/{version}/mytool_{os}_{arch}.{ext}"
  version_url:  "https://dl.example.com/mytool/latest.txt"

The version endpoint is a one-line text file the publish step overwrites. Works for S3 static hosting, a CDN, Nexus, Artifactory, or any plain web server.

GitHub releases, without a GitHub provider¶

Useful when you want GitHub's asset hosting but not its API client in your dependency graph. The download URLs are predictable, and the version comes from the public API as plain JSON:

direct:
  tool_name:    my-tool
  url_template: "https://github.com/myorg/my-tool/releases/download/{version}/{tool}_{os}_{arch}.{ext}"
  version_url:  "https://api.github.com/repos/myorg/my-tool/releases/latest"
  version_key:  "tag_name"

Unauthenticated GitHub API calls are rate-limited per IP; set DIRECT_TOKEN, or compose a credential of your own, if that bites.

A pinned internal distribution¶

direct:
  tool_name:      mytool
  url_template:   "https://artifacts.corp.internal/mytool/{version}/mytool_{os}_{arch}.{ext}"
  pinned_version: "v1.4.2"

No version endpoint, so the tool only ever installs what the pin names. Useful where rollout is controlled by changing configuration rather than by publishing.

Credentials¶

The provider composes three sources, in this order: the standard key, the legacy scalar, then the well-known environment variable.

direct.auth.value is read from whatever layer supplies it: an env layer, a keychain layer, a file. That is where the precedence belongs. Or take over the composition entirely:

settings.Credential = forge.StaticCredential(tokenFromMyOwnLoginFlow)

The legacy direct.token scalar still works, composed below auth.value, so existing configuration keeps running.

The token travels as an Authorization: Bearer header and, unlike the forge-backed providers, it is attached to whatever URL the template produced, with no HostTrusted pin.

It does not survive a redirect leaving that origin. Authorization is registered as a sensitive header, so it is deleted on any hop where the scheme, host or port changes. That is stricter than the standard library, which strips Authorization cross-host but compares the domain and ignores the port. That is defensible here because the template is operator-supplied rather than release-author-supplied, but it does mean a template pointing at a third party sends your token there. Point it only at hosts you control.

What it does not do¶

ListReleases returns ErrNotSupported, because a URL template cannot be enumerated.

GetReleaseByTag synthesises a release for any tag you ask for, because with no API there is nothing to check against; a wrong tag surfaces as a 404 at download time rather than at lookup.

The synthesised release exposes exactly one asset, and its name is <tag>.tar.gz, so v1.2.3.tar.gz, whatever filename url_template produces. Code that finds an asset by matching a filename convention will not find this one; take the single asset the release gives you.

There is no Repositories, Contents, Sites, Issues or IssueFiler support, and there never will be. A web server is not a forge.

Related¶

• Authenticate to a forge
• Verify checksums and signatures
• Configuration: every key with its default
• What forge does not do