feat: support configurable hosted upstream

[jiechic]

Summary

This PR makes PubNet's hosted upstream configurable instead of hardcoding https://pub.dev/api/.

It adds support for configuring the upstream through application configuration or environment variables, while keeping https://pub.dev/api/ as the fallback default.

Why

Today, PubNet can fall back to pub.dev for package metadata and archive downloads, but the upstream is fixed in code.

Making the upstream configurable improves deployment flexibility in cases such as:

• falling back to an existing unpub deployment during a migration to PubNet
• using an internal hosted repository as the upstream source
• using a regional mirror when direct access to pub.dev is slow or unreliable
• using a China-based mirror or another regional mirror where direct access to pub.dev is unstable

This makes it easier to use PubNet as the main entry point while still relying on another hosted repository for packages that are not stored
locally.

Changes

• Add configurable HostedUpstream:BaseUrl
• Support environment variable override via HostedUpstream__BaseUrl
• Fall back to https://pub.dev/api/ when the configured value is missing or invalid
• Switch upstream client requests to relative paths so path-prefixed upstream base URLs work correctly
• Document JSON configuration, environment variable usage, and Docker Compose examples in the README

Notes on URL handling

The upstream client now uses relative request paths such as:

• packages/{name}
• packages/{name}/versions/{version}

instead of absolute paths starting with /api/....

This is important because absolute paths would ignore any configured path prefix in BaseAddress. Using relative paths ensures values like:

• https://pub.dev/api/
• https://unpub.example.com/api/
• https://example.com/some/prefix/api/

all resolve correctly.

Example configuration

{
  "HostedUpstream": {
    "BaseUrl": "https://unpub.example.com/api/"
  }
}

Or through environment variables:

HostedUpstream__BaseUrl=https://unpub.example.com/api/

## Validation

I do not currently have a working verification environment for this repository, so this PR has not been runtime-validated.

Specifically:

- I did not run a full build locally
- I did not run tests
- I did not validate the behavior against a live unpub deployment or a regional mirror

The change was made based on code inspection and URI resolution behavior, but it should still be reviewed and verified in a proper
development environment before merge.

[ricardoboss]

Hi! Thanks for opening a PR.

This is a great suggestion and I want to include it. For options and option validation, we should use .NETs options pattern (linked below).

[jiechic]

Thanks for the review! I've pushed a follow-up commit addressing all the feedback:

• Validation now uses the options pattern: a new HostedUpstreamOptions bound via AddOptions().BindConfiguration().Validate().ValidateOnStart(). Instead of logging a warning and silently falling back to pub.dev, an invalid BaseUrl now fails fast at startup.
• Default values removed from appsettings.json, appsettings.Development.json, and backend-appsettings.json — the default (https://pub.dev/api/) now lives in HostedUpstreamOptions.BaseUrl.

One behavior change worth flagging: previously an invalid URL fell back to the default at runtime; now it throws at startup. Happy to keep the fallback behavior instead if you'd prefer that.

Still haven't been able to runtime-validate locally, so a check in a proper dev environment would be appreciated.

[ricardoboss]

Thanks for making the changes!

If you could just add a single line to CHANGELOG.md documenting the new option too!

[jiechic]

Done! I've added the HostedUpstream option to CHANGELOG.md.