Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,65 @@ end

After you are done, run `mix deps.get` in your shell to fetch the dependencies.

## Release retention

Inspect and prune existing releases on the configured hosts:

```sh
mix dicon.prune --dry-run
mix dicon.prune --only app01
```

Both commands print the retained versions and each deletion per host. `--only`
and `--skip` can be repeated, just as for deploy and switch.

Standalone pruning keeps the directory `current` resolves to and **one previous
version**: the highest stable (non-pre-release) version strictly below current
according to `Version.compare/2`. If no lower stable version exists, it falls
back to the highest pre-release below current. For example, current `1.7.6`
keeps `1.7.5` and deletes an unused `1.7.6-rc4`. Current may itself be an RC.
Build metadata does not affect precedence; ties for previous are broken by
directory name in ascending lexical order. If no older version exists, only
current is kept.

Every other directory with a valid Elixir SemVer name is deleted, including
newer unswitched releases and abandoned experiments. Non-version entries such
as `log/`, files and symlinks are untouched. A missing, broken, non-version or
external `current` stops pruning without deleting releases on that host.

For automatic cleanup, opt in per application:

```elixir
config :dicon, prune_on_switch: true
```

Automatic pruning retains **the exact release current pointed to before the
switch**, whether it is stable, an RC, or newer than the requested version during
rollback. Each host's old current is read and validated before switching; cleanup
then verifies that current resolves to the requested version. Thus switching
from `1.7.5` to `1.7.6` keeps `1.7.5` and deletes an unused `1.7.6-rc4`. This
preserves the old release throughout a `switch → stop → start` sequence.

If current is absent on the first switch, cleanup keeps only the new release.
An invalid existing current aborts before switching. Switching to the
already-current version skips pruning so a retry preserves the rollback target.
`dicon.deploy` never prunes, so uploading before switching remains safe. Automatic
cleanup defaults to off because dicon is shared by services with different staging
and retention workflows; services must enable it to bound disk growth.

Serialize deploy, switch and prune operations on each host. Never run standalone
pruning between deploy and switch: it removes the staged release. The commands
recheck current before each deletion but do not lock concurrent deployments.
Standalone pruning has no switch history: inspect its dry run and stop any process
using a release it would delete before running it. It can remove an RC or newer
release that automatic pruning retained as the previous current.

Rollback to the retained previous version uses the usual `mix dicon.switch
VERSION`. Automatic pruning keeps the release rolled back from, so rolling
forward to it requires no redeploy. Pruning errors abort the task; they do not
undo an already completed switch or earlier deletions. Inspect the reported host
before retrying; standalone pruning uses the stable-first policy described above.

## License

This software is licensed under [the ISC license](LICENSE).
7 changes: 7 additions & 0 deletions lib/dicon.ex
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,13 @@ defmodule Dicon do
* `:executor` - a module that will be used to execute commands on servers.
By default, it's `Dicon.SecureShell`.

* `:prune_on_switch` - a boolean, defaulting to `false`. When enabled,
`dicon.switch` prunes each host after switching, keeping current and the
release current pointed to before the switch, even if it is an RC or newer
than current after rollback. All other version directories are removed.
Switching to the already-current version skips pruning. See `dicon.prune` and
the README for ordering and rollback requirements.

### Configuration for hosts

Each host listed in the `:hosts` configuration option mentioned above can be
Expand Down
161 changes: 161 additions & 0 deletions lib/dicon/pruner.ex
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
defmodule Dicon.Pruner do
@moduledoc false

alias Dicon.Executor

# SecureShell does not propagate remote exit statuses. Require this marker only
# after every shell operation succeeds, including a complete directory listing.
@success "dicon:prune:ok"

def current_version(%Executor{} = conn, target_dir, host) when is_binary(target_dir) do
{_root, current, _releases} = inventory(conn, target_dir, host)
current
end

def prune(%Executor{} = conn, target_dir, host, opts \\ []) when is_binary(target_dir) do
{root, current, releases} = inventory(conn, target_dir, host)

if is_nil(current) do
Mix.raise("#{host}: current is missing; refusing to prune")
end

if expected = opts[:expected_current] do
if current != expected do
Mix.raise("#{host}: current is #{current}, expected #{expected}; refusing to prune")
end
end

previous_name = previous_version(releases, current, host, opts)
Mix.shell().info("#{host}: keeping current #{current}, previous #{previous_name || "none"}")

for {name, _} <- releases, name not in [current, previous_name] do
path = Path.join(root, name)

if opts[:dry_run] do
Mix.shell().info("#{host}: would delete #{path}")
else
checked_exec(conn, [
"cd ",
quote_path(root),
" && test -L current && test \"$(cd current && pwd -P)\" = ",
quote_path(Path.join(root, current)),
" && test ! -L ",
quote_path("./" <> name),
" && test -d ",
quote_path("./" <> name),
" && rm -rf -- ",
quote_path("./" <> name)
])

Mix.shell().info("#{host}: deleted #{path}")
end
end

:ok
end

defp previous_version(releases, current, host, opts) do
case Keyword.fetch(opts, :keep_previous) do
{:ok, nil} ->
nil

{:ok, previous} when is_binary(previous) ->
if not List.keymember?(releases, previous, 0) do
Mix.raise("#{host}: previous release #{previous} is missing; refusing to prune")
end

previous

:error ->
older =
Enum.filter(releases, fn {_, %Version{} = version} ->
Version.compare(version, current) == :lt
end)

previous =
Enum.find(older, fn {_, %Version{pre: pre}} -> pre == [] end) || List.first(older)

if previous, do: elem(previous, 0)
end
end

defp inventory(%Executor{} = conn, target_dir, host) when is_binary(target_dir) do
target_dir = if Path.type(target_dir) == :absolute, do: target_dir, else: "./" <> target_dir

output =
checked_exec(conn, [
"cd ",
quote_path(target_dir),
" && root=$(pwd -P)",
" && if test ! -e current && test ! -L current; then current='';",
" else test -L current && current=$(cd current && pwd -P); fi",
" && printf '%s\\0' \"$root\" \"$current\"",
" && find . -mindepth 1 -maxdepth 1 -type d -print0"
])

parse_inventory(output, host)
end

defp parse_inventory(output, host) when is_binary(output) do
case String.split(output, "\0", trim: false) do
["/" <> _ = root, current_path | entries] ->
releases =
entries
|> Enum.flat_map(fn
"./" <> name ->
case Version.parse(name) do
{:ok, version} -> [{name, version}]
:error -> []
end

_ ->
[]
end)
|> Enum.sort(fn {left_name, left}, {right_name, right} ->
case Version.compare(left, right) do
:gt -> true
:lt -> false
:eq -> left_name <= right_name
end
end)

current =
if current_path != "" do
name = Path.basename(current_path)

if Path.dirname(current_path) != root or not List.keymember?(releases, name, 0) do
Mix.raise("#{host}: current must resolve to a version directory inside #{root}")
end

name
end

{root, current, releases}

_ ->
Mix.raise("#{host}: invalid release inventory; refusing to prune")
end
end

defp checked_exec(%Executor{} = conn, command) do
{:ok, device} = StringIO.open("")
success = "\0" <> @success <> "\0"

try do
Executor.exec(conn, [command, " && printf '\\0%s\\0' ", quote_path(@success)], device)
{"", output} = StringIO.contents(device)

if String.ends_with?(output, success) do
binary_part(output, 0, byte_size(output) - byte_size(success))
else
Mix.raise("Pruning command failed or current changed; refusing to continue: #{output}")
end
after
StringIO.close(device)
end
end

defp quote_path(path) when is_binary(path) do
"'" <> String.replace(path, "'", "'\\''") <> "'"
end
end
52 changes: 52 additions & 0 deletions lib/mix/tasks/dicon.prune.ex
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
defmodule Mix.Tasks.Dicon.Prune do
use Mix.Task

@shortdoc "Keeps current and the previous release on the configured servers"

@moduledoc """
Deletes version directories except current and the highest stable SemVer below
it. If no lower stable version exists, keeps the highest pre-release below
current instead. All other versions, including newer versions, are deleted.
Non-version entries and symlinks are left alone. Unlike automatic pruning on
switch, this task has no record of the release previously selected by current.

The configured hosts and target directory come from the application's `:dicon`
configuration. Use `--only HOST` / `--skip HOST` to filter hosts and `--dry-run`
to print the deletions without changing anything.

Run only after switching and stopping any process that uses a release to be
deleted. Serialize deploy, switch and prune operations for each host; never
prune between uploading a release and switching to it. An invalid or missing
`current` aborts pruning. See the README for rollback and automatic pruning.

## Usage

mix dicon.prune --dry-run
mix dicon.prune --only app01
"""

import Dicon, only: [config: 1, config: 2, host_config: 1]

alias Dicon.{Executor, Pruner}

@options [strict: [only: :keep, skip: :keep, dry_run: :boolean]]

def run(argv) do
case OptionParser.parse(argv, @options) do
{opts, [], []} ->
target_dir = config(:target_dir)

for host <- config(:hosts, opts) do
{authority, host_config} = Keyword.pop!(host_config(host), :authority)
conn = Executor.connect(authority, host_config)
Pruner.prune(conn, target_dir, host, opts)
end

{_opts, _commands, [switch | _]} ->
Mix.raise("Invalid option: " <> Mix.Dicon.switch_to_string(switch))

{_opts, _commands, _errors} ->
Mix.raise("Expected no arguments")
end
end
end
16 changes: 16 additions & 0 deletions lib/mix/tasks/dicon.switch.ex
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,11 @@ defmodule Mix.Tasks.Dicon.Switch do
the currently active release to the one specified by the given version. Switching
versions won't affect the running application.

With `config :dicon, prune_on_switch: true`, each host is pruned after switching,
keeping current and the release current pointed to before the switch. Switching
to the already-current version skips pruning to preserve the rollback target. See
`mix help dicon.prune` and the README for the retention and rollback policy.

## Usage

mix dicon.switch VERSION
Expand Down Expand Up @@ -42,7 +47,18 @@ defmodule Mix.Tasks.Dicon.Switch do
for host <- config(:hosts, opts) do
{authority, host_config} = Keyword.pop!(host_config(host), :authority)
conn = Executor.connect(authority, host_config)
prune? = Application.get_env(:dicon, :prune_on_switch, false)

previous = if prune?, do: Dicon.Pruner.current_version(conn, config(:target_dir), host)

symlink(conn, [target_dir, ?/, version], [target_dir, "/current"])

if prune? and previous != version do
Dicon.Pruner.prune(conn, config(:target_dir), host,
expected_current: version,
keep_previous: previous
)
end
end

{_opts, _commands, [switch | _]} ->
Expand Down
Loading