Initial commit

Author: tomchkk

.gitignore

@@ -0,0 +1,6 @@
+composer.lock
+.phpunit.result.cache
+vendor/
+
+cache/
+!cache/.gitkeep

README.md

@@ -0,0 +1,6 @@
+Laravel Mutex Migrations
+========================
+
+Run mutually exclusive migrations from more than one server at a time.
+
+TODO:

composer.json

@@ -0,0 +1,50 @@
+{
+    "name": "netsells/laravel-mutex-migrations",
+    "description": "Run mutually exclusive migrations from more than one server at a time",
+    "type": "library",
+    "license": "MIT",
+    "keywords": [
+        "laravel",
+        "netsells",
+        "migrations",
+        "mutex"
+    ],
+    "authors": [
+        {
+            "name": "Tom Moore",
+            "email": "[email protected]"
+        },
+        {
+            "name": "Sam Jordan",
+            "email": "[email protected]"
+        }
+    ],
+    "require": {
+        "php": "^8.1",
+        "laravel/framework": "^9.3"
+    },
+    "require-dev": {
+        "orchestra/testbench": "^7.7",
+        "spatie/fork": "^1.1"
+    },
+    "autoload": {
+        "psr-4": {
+            "Netsells\\LaravelMutexMigrations\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Netsells\\LaravelMutexMigrations\\Tests\\": "tests/"
+        }
+    },
+    "extra": {
+        "laravel": {
+            "providers": [
+                "Netsells\\LaravelMutexMigrations\\ServiceProvider"
+            ]
+        }
+    },
+    "config": {
+        "sort-packages": true
+    }
+}

config/mutex-migrations.php

@@ -0,0 +1,46 @@
+<?php
+
+return [
+    'command' => [
+
+        // configuration for running migrations in maintenance mode
+        'down' => [
+            // options for the artisan down command called during a down
+            // migration @see \Illuminate\Foundation\Console\DownCommand
+            'options' => [
+                // The path that users should be redirected to
+                '--redirect' => null,
+                // The view that should be pre-rendered for display during
+                // maintenance mode
+                '--render' => null,
+                // The number of seconds after which the request may be retried
+                '--retry' => null,
+                // The number of seconds after which the browser may refresh
+                '--refresh' => null,
+                // The secret phrase that may be used to bypass maintenance mode
+                '--secret' => null,
+                // The status code that should be used when returning the
+                // maintenance mode response
+                '--status' => null,
+            ],
+
+            // preserves maintenance mode after an exception during a down
+            // migration
+            'sticky' => true,
+        ],
+    ],
+
+    'queue' => [
+        // the cache store to use to manage queued migrations; use stores that
+        // are available across application instances, such as 'database', or
+        // 'redis' to ensure migrations are mutually exclusive. N.B. mutually
+        // exclusive migrations using the 'database' store can only work after
+        // the store's `cache` table has been created (by a standard migration!)
+        'store' => env('MUTEX_MIGRATIONS_STORE', 'database'),
+
+        // the maximum number of seconds a mutex migration should wait while
+        // trying to acquire a lock - effectively the time an instance of a
+        // mutex migration has to complete - before an exception is thrown
+        'ttl_seconds' => env('MUTEX_MIGRATIONS_TTL_SECONDS', 60),
+    ]
+];

phpunit.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true">
+    <testsuites>
+        <testsuite name="Integration">
+            <directory suffix="Test.php">./tests/Integration</directory>
+        </testsuite>
+        <testsuite name="Unit">
+            <directory suffix="Test.php">./tests/Unit</directory>
+        </testsuite>
+    </testsuites>
+    <php>
+        <env name="DB_CONNECTION" value="testing"/>
+        <env name="MUTEX_MIGRATIONS_STORE" value="file"/>
+    </php>
+</phpunit>

src/MigrateCommandExtension.php

@@ -0,0 +1,90 @@
+<?php
+
+namespace Netsells\LaravelMutexMigrations;
+
+use Illuminate\Contracts\Events\Dispatcher;
+use Illuminate\Database\Console\Migrations\MigrateCommand;
+use Illuminate\Database\Migrations\Migrator;
+use Netsells\LaravelMutexMigrations\Processors\MigrationProcessorFactory;
+use Netsells\LaravelMutexMigrations\Processors\MigrationProcessorInterface;
+use Symfony\Component\Console\Command\SignalableCommandInterface;
+use Symfony\Component\Console\Input\InputOption;
+
+class MigrateCommandExtension extends MigrateCommand implements SignalableCommandInterface
+{
+    private const OPTION_DOWN = 'down';
+
+    private const OPTION_MUTEX = 'mutex';
+
+    private MigrationProcessorInterface $processor;
+
+    public function __construct(
+        Migrator $migrator,
+        Dispatcher $dispatcher,
+        private readonly MigrationProcessorFactory $factory
+    ) {
+        $this->extendSignature();
+
+        parent::__construct($migrator, $dispatcher);
+    }
+
+    public function handle()
+    {
+        $this->processor = $this->createProcessor();
+
+        try {
+            $this->processor->start();
+
+            return parent::handle();
+        } catch (\Throwable $th) {
+            $this->components->error($th->getMessage());
+
+            return self::FAILURE;
+        } finally {
+            $this->processor->terminate(isset($th));
+        }
+    }
+
+    private function createProcessor(): MigrationProcessorInterface
+    {
+        return $this->factory->create(
+            $this->option(self::OPTION_MUTEX),
+            $this->option(self::OPTION_DOWN),
+            $this,
+            $this->components
+        );
+    }
+
+    public function getSubscribedSignals(): array
+    {
+        return [SIGINT, SIGTERM];
+    }
+
+    public function handleSignal(int $signal): void
+    {
+        $this->processor->terminate(false);
+    }
+
+    private function extendSignature(): void
+    {
+        $this->signature = join(PHP_EOL, array_merge(
+            [$this->signature],
+            array_map(function ($option) {
+                return '{--' . join(" : ", [$option[0], $option[3]]) . '}';
+            }, $this->getAdditionalOptions())
+        ));
+    }
+
+    /**
+     * Additional options to add to the command.
+     *
+     * @return array
+     */
+    private function getAdditionalOptions(): array
+    {
+        return [
+            [self::OPTION_MUTEX, null, InputOption::VALUE_NONE, 'Run a mutually exclusive migration'],
+            [self::OPTION_DOWN, null, InputOption::VALUE_NONE, 'Enable maintenance mode during a migration']
+        ];
+    }
+}

src/Mutex/DatabaseCacheTableNotFoundException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Netsells\LaravelMutexMigrations\Mutex;
+
+class DatabaseCacheTableNotFoundException extends \Exception
+{
+    public function __construct()
+    {
+        parent::__construct(
+            'Mutex migrations cannot be run using the database store until the required cache tables have been created. Run `php artisan cache:table` to create the required migration followed by a standard migration to create the tables.'
+        );
+    }
+}

src/Mutex/MutexQueue.php

@@ -0,0 +1,90 @@
+<?php
+
+namespace Netsells\LaravelMutexMigrations\Mutex;
+
+use Illuminate\Contracts\Cache\LockProvider;
+use Illuminate\Contracts\Cache\Repository;
+
+class MutexQueue
+{
+    public const KEY = 'laravel-mutex-migrations';
+
+    public function __construct(
+        private readonly Repository $cache,
+        private readonly int $ttl_seconds = 60
+    ) {
+        //
+    }
+
+    public function push(string $item, array $meta = []): bool
+    {
+        if ($this->contains($item)) {
+            return false;
+        }
+
+        return $this->withAtomicLock(function () use ($item, $meta) {
+            $items = $this->getItems();
+            $items[$item] = $meta;
+
+            return $this->putItems($items);
+        });
+    }
+
+    public function pull(string $item): bool
+    {
+        if (! $this->contains($item)) {
+            return false;
+        }
+
+        return $this->withAtomicLock(function () use ($item) {
+            $filteredItems = array_filter(
+                $this->getItems(),
+                fn (string $key) => $key !== $item,
+                ARRAY_FILTER_USE_KEY
+            );
+
+            return empty($filteredItems)
+                ? $this->cache->forget(self::KEY)
+                : $this->putItems($filteredItems);
+        });
+    }
+
+    public function contains(string|callable $item): bool
+    {
+        if (is_string($item)) {
+            return in_array($item, array_keys($this->getItems()));
+        }
+
+        return ! empty(array_filter($this->getItems(), $item, ARRAY_FILTER_USE_BOTH));
+    }
+
+    public function isEmpty(): bool
+    {
+        return empty($this->getItems());
+    }
+
+    public function isFirst(string $item): bool
+    {
+        $keys = array_keys($this->getItems());
+
+        return reset($keys) === $item;
+    }
+
+    private function withAtomicLock(callable $callback)
+    {
+        /** @var LockProvider $provider */
+        $provider = $this->cache->getStore();
+
+        return $provider->lock(self::KEY . '.lock', 3)->block(2, $callback);
+    }
+
+    private function getItems(): array
+    {
+        return $this->cache->get(self::KEY, []);
+    }
+
+    private function putItems(array $items): bool
+    {
+        return $this->cache->put(self::KEY, $items, $this->ttl_seconds);
+    }
+}