feat(snap): run gateway as a user service by default (#4099)

* feat(snap): run gateway as a user service by default

Replace the existing system `gateway` service with separate
`user-gateway` and `system-gateway` services. For new installs, only the
`user-gateway` service is enabled. For existing installs, only the
`system-gateway` service is enabled.

Existing installs continue to have a one-time migration which removes
legacy insecure configurations. It is up to `install.sh` or users to
manually copy mTLS credentials from the root-owned `$SNAP_COMMON/tls` to
the invoking user's OpenShell snap directory. This is explained in the
snap description in `snapcraft.yaml`, visible in the Snap Store listing
and via `snap info openshell`.

Service enablement is now managed by a new snap configuration option
named `gateway-mode`, so users can switch from one mode to another via
e.g. `sudo snap set openshell gateway-mode=user`. The `install` and
`post-refresh` hooks select which service to start by setting this mode.
If the `gateway-mode` is already set, then we know the one-time
migration has already taken place.

Signed-off-by: Oliver Calder <oliver.calder@canonical.com>

* fix(snap): simplify the snap gateway wrapper

Signed-off-by: Oliver Calder <oliver.calder@canonical.com>

* fix(snap): use `snap start --user` when running as non-root

Signed-off-by: Oliver Calder <oliver.calder@canonical.com>

* fix(snap): ensure install.sh waits for the correct docker daemon

Signed-off-by: Oliver Calder <oliver.calder@canonical.com>

* feat(snap): document how to safely switch between gateway modes

New installs run the gateway as a user service by default, while
upgrades of existing installs from prior to the user gateway continue to
use the existing system gateway. The user and system gateway are
fundamentally different services and there is no way to migrate state
between them.

However, it may be desirable for a user to run the gateway as a system
service after a fresh install. To support this, this commit adds
documentation for how to safely transition from the user gateway mode to
the system gateway mode, and vice versa.

Also, clarifies when it is necessary to manually copy TLS credentials
from the system gateway state directory to the user's home directory:
when upgrading a pre-TLS snap installation, or when switching from user
to system gateway mode. When upgrading an existing install with an HTTPS
gateway running as a system service, copying credentials again is not
necessary.

Signed-off-by: Oliver Calder <oliver.calder@canonical.com>

---------

Signed-off-by: Oliver Calder <oliver.calder@canonical.com>

python/openshell/release_formula_test.py

@@ -151,19 +151,12 @@ def test_snap_wrapper_uses_optional_gateway_config_without_generating_toml() ->
     )
 
     assert "init-gateway-config.sh" not in wrapper
-    assert (
-        'export OPENSHELL_DB_URL="${OPENSHELL_DB_URL:-sqlite:${SNAP_COMMON}/gateway.db?mode=rwc}"'
-        in wrapper
-    )
+    assert "CANONICAL_CONFIG_FILE" not in wrapper
+    assert '[ -z "${OPENSHELL_GATEWAY_CONFIG:-}" ]' in wrapper
+    assert 'export OPENSHELL_GATEWAY_CONFIG="$OPENSHELL_SNAP_CONFIG_FILE"' in wrapper
+    assert "export OPENSHELL_DB_URL=" not in wrapper
     assert "OPENSHELL_DISABLE_TLS" not in wrapper
-    assert (
-        'export OPENSHELL_LOCAL_TLS_DIR="${OPENSHELL_LOCAL_TLS_DIR:-${SNAP_COMMON}/tls}"'
-        in wrapper
-    )
-    assert (
-        'exec "${SNAP}/bin/openshell-gateway" --config "$CANONICAL_CONFIG_FILE" "$@"'
-        in wrapper
-    )
+    assert 'export OPENSHELL_LOCAL_TLS_DIR="${XDG_STATE_HOME}/openshell/tls"' in wrapper
     assert 'exec "${SNAP}/bin/openshell-gateway" "$@"' in wrapper
 
 
@@ -249,17 +242,8 @@ def test_schema_v2_debian_and_snap_preflight_wiring() -> None:
     assert "ExecStart=/usr/bin/openshell-gateway" in unit
     assert "$src_dir/openshell-gateway.service" in package_deb
     assert "$pkgroot/usr/lib/systemd/user/openshell-gateway.service" in package_deb
-    assert 'if [ -n "${OPENSHELL_GATEWAY_CONFIG:-}" ]; then' in wrapper
-    assert (
-        'elif [ -e "$CANONICAL_CONFIG_FILE" ] || [ -L "$CANONICAL_CONFIG_FILE" ]; then'
-        in wrapper
-    )
-    assert wrapper.count('"${SNAP}/bin/openshell-gateway" config preflight') == 4
+    assert '[ -z "${OPENSHELL_GATEWAY_CONFIG:-}" ]' in wrapper
+    assert 'export OPENSHELL_GATEWAY_CONFIG="$OPENSHELL_SNAP_CONFIG_FILE"' in wrapper
+    assert wrapper.count('"${SNAP}/bin/openshell-gateway" config preflight') == 1
     assert 'config preflight -- "$@"' in wrapper
-    assert 'config preflight -- --config "$CANONICAL_CONFIG_FILE" "$@"' in wrapper
-    assert (
-        'exec "${SNAP}/bin/openshell-gateway" --config "$CANONICAL_CONFIG_FILE" "$@"'
-        in wrapper
-    )
-    assert wrapper.count('exec "${SNAP}/bin/openshell-gateway" "$@"') == 3
-    assert '[ -f "$CANONICAL_CONFIG_FILE" ]' not in wrapper
+    assert wrapper.count('exec "${SNAP}/bin/openshell-gateway" "$@"') == 1