Skip to content

[FEATURE] get-stackql.io: optional version argument to install a specific release #931

Closed

Description

@jeffreyaven

Summary

get-stackql.io (the Cloudflare Worker in get-app/) always installs the latest release. Add an optional version argument, as a query param or a path segment, so a specific release can be installed. With no version given the behaviour is unchanged and the latest release is installed.

Current behaviour

  • RELEASE_BASE is hardcoded to https://releases.stackql.io/stackql/latest in get-app/src/index.ts, and every endpoint (/, /install, /install.sh, /install.ps1, /install/<provider>) builds its download URL from it.
  • The fetch handler only reads url.pathname and the User-Agent, so query strings are ignored. curl -fsSL "https://get-stackql.io/install?version=0.12.824" currently returns a script with base="https://releases.stackql.io/stackql/latest".
  • /install/0.12.824 is routed as a cloud shell provider and returns no cloud shell helper named '0.12.824'.
  • The generated sh and PowerShell installers take no arguments and read no env vars.

The download host already serves versioned paths, so this is a worker-only change:

URL Status
https://releases.stackql.io/stackql/latest/stackql_linux_amd64.zip 200
https://releases.stackql.io/stackql/0.12.824/stackql_linux_amd64.zip 200
https://releases.stackql.io/stackql/v0.12.824/stackql_linux_amd64.zip 404

Proposed usage

Query param:

curl -fsSL "https://get-stackql.io/install?version=0.12.824" | sh
curl -fsSL "https://get-stackql.io/install/aws?version=0.12.824" | sh
curl -sI "https://get-stackql.io/?version=0.12.824"    # 302 to the versioned asset
irm "https://get-stackql.io/install.ps1?version=0.12.824" | iex

Path segment. /install/<segment> is already taken by cloud shell providers, so the version needs a position that doesn't collide, for example a leading segment:

curl -fsSL https://get-stackql.io/v0.12.824/install | sh
curl -fsSL https://get-stackql.io/v0.12.824/install/aws | sh
curl -sI https://get-stackql.io/v0.12.824              # 302 to the versioned asset
irm https://get-stackql.io/v0.12.824/install.ps1 | iex

The path form needs no quoting. The query form does in zsh, where an unquoted ? is treated as a glob and fails with no matches found.

Supporting both is fine. They would resolve to the same internal version value.

Implementation notes

  • Accept 0.12.824 or v0.12.824 and strip a leading v. releases.stackql.io uses unprefixed versions (the v path returns 404), while GitHub tags use the v prefix.
  • Validate against a strict pattern such as ^v?\d+\.\d+\.\d+$ before using it. The value is interpolated into the served script, so arbitrary input must not be reflected. On an invalid value, serve a short error script in the caller's shell language, following the existing wrong-shell guards.
  • Treat latest or no value as the current behaviour.
  • For the path form, strip a leading version segment before the existing routing runs (the cloud shell check currently expects exactly two segments).
  • Turn RELEASE_BASE into a function of the version and pass it through to INSTALL_SH, INSTALL_PS1, providerInstallSh() and the / redirect. When a version is pinned, RELEASES_URL in error messages should point at https://github.com/stackql/stackql/releases/tag/v<version>.
  • Older releases don't carry every asset. v0.12.732 and earlier have no stackql_windows_arm64.zip, and 0.5.418 has no stackql_linux_arm64.zip (404 on releases.stackql.io). The installers curl -fsSL / Invoke-WebRequest straight to the asset, so a missing version or asset currently surfaces as a raw HTTP 404. They should catch that and print something like stackql <version> has no <asset> - see <release url>.
  • Unknown versions can be handled the same way in the installer, or the worker could HEAD the asset before serving the script. The installer-side check is simpler and keeps the worker free of subrequests.
  • Update get-app/README.md and the smoke tests (test-get-app.sh, test-get-app.ps1).

Acceptance criteria

  • No version -> unchanged behaviour (latest).
  • 0.12.824 and v0.12.824 both install 0.12.824 via /, /install, /install.sh, /install.ps1 and /install/<provider>.
  • Invalid version strings are rejected with a readable message and are never echoed into the served script unsanitized.
  • A version and architecture combination with no matching asset fails with a readable message, not a bare HTTP 404.
  • Smoke tests cover a pinned version, v-prefixed input, an invalid value and a missing asset.

Activity

  1. jeffreyaven commented on Nov 18, 2026

    @jeffreyaven
    MemberAuthor

    Resolved in PR #936, merged as 256187f.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions