Merge pull request #1 from stancl/shared-users

Shared users

src/Contracts/SyncMaster.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Stancl\Tenancy\Contracts;
+
+use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+
+/**
+ * @property-read Tenant[]|Collection $tenants
+ */
+interface SyncMaster extends Syncable
+{
+    public function tenants(): BelongsToMany;
+    public function getTenantModelName(): string;
+}

src/Contracts/Syncable.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Stancl\Tenancy\Contracts;
+
+interface Syncable
+{
+    public function getGlobalIdentifierKeyName(): string;
+    public function getGlobalIdentifierKey(): string;
+    public function getCentralModelName(): string;
+    public function getSyncedAttributeNames(): array;
+}

src/Contracts/UniqueIdentifierGenerator.php

@@ -4,12 +4,10 @@ declare(strict_types=1);
 
 namespace Stancl\Tenancy\Contracts;
 
-use Stancl\Tenancy\Database\Models\Tenant;
-
 interface UniqueIdentifierGenerator
 {
     /**
      * Generate a unique identifier.
      */
-    public static function generate(Tenant $tenant): string;
+    public static function generate($resource): string;
 }

src/Database/Models/Concerns/ResourceSyncing.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Stancl\Tenancy\Database\Models\Concerns;
+
+use Stancl\Tenancy\Contracts\Syncable;
+use Stancl\Tenancy\Contracts\UniqueIdentifierGenerator;
+use Stancl\Tenancy\Events\SyncedResourceSaved;
+
+trait ResourceSyncing
+{
+    public static function bootResourceSyncing()
+    {
+        static::saved(function (Syncable $model) {
+            /** @var ResourceSyncing $model */
+
+            $model->triggerSyncEvent();
+        });
+
+        static::creating(function (self $model) {
+            if (! $model->getAttribute($model->getGlobalIdentifierKeyName()) && app()->bound(UniqueIdentifierGenerator::class)) {
+                $model->setAttribute(
+                    $model->getGlobalIdentifierKeyName(),
+                    app(UniqueIdentifierGenerator::class)->generate($model)
+                );
+            }
+        });
+    }
+
+    public function triggerSyncEvent()
+    {
+        /** @var Syncable $this */
+        event(new SyncedResourceSaved($this, tenant()));
+    }
+}

src/Database/Models/TenantPivot.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Stancl\Tenancy\Database\Models;
+
+use Illuminate\Database\Eloquent\Relations\Pivot;
+use Stancl\Tenancy\Contracts\Syncable;
+
+class TenantPivot extends Pivot
+{
+    public static function booted()
+    {
+        static::saved(function (self $pivot) {
+            $parent = $pivot->pivotParent;
+
+            if ($parent instanceof Syncable) {
+                $parent->triggerSyncEvent();
+            }
+        });
+    }
+}

src/DatabaseManager.php

@@ -42,9 +42,9 @@ class DatabaseManager
      */
     public function connectToTenant(TenantWithDatabase $tenant)
     {
+        $this->database->purge('tenant');
         $this->createTenantConnection($tenant);
         $this->setDefaultConnection('tenant');
-        $this->database->purge('tenant');
     }
 
     /**
@@ -55,6 +55,7 @@ class DatabaseManager
         if (tenancy()->initialized) {
             $this->database->purge('tenant');
         }
+
         $this->setDefaultConnection($this->config->get('tenancy.central_connection'));
     }
 

src/Events/Listeners/QueueableListener.php

@@ -4,12 +4,13 @@ namespace Stancl\Tenancy\Events\Listeners;
 
 use Illuminate\Contracts\Queue\ShouldQueue;
 
+/**
+ * @method handle(object $event)
+ */
 abstract class QueueableListener implements ShouldQueue
 {
     public static $shouldQueue = false;
 
-    abstract public function handle();
-
     public function shouldQueue($event)
     {
         if (static::$shouldQueue) {

src/Events/Listeners/UpdateSyncedResource.php

@@ -0,0 +1,121 @@
+<?php
+
+namespace Stancl\Tenancy\Events\Listeners;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\Pivot;
+use Stancl\Tenancy\Contracts\SyncMaster;
+use Stancl\Tenancy\Events\SyncedResourceChangedInForeignDatabase;
+use Stancl\Tenancy\Events\SyncedResourceSaved;
+use Stancl\Tenancy\Exceptions\ModelNotSyncMaster;
+
+class UpdateSyncedResource extends QueueableListener
+{
+    public static $shouldQueue = false;
+
+    public function handle(SyncedResourceSaved $event)
+    {
+        $syncedAttributes = $event->model->only($event->model->getSyncedAttributeNames());
+
+        // We update the central record only if the event comes from tenant context.
+        if ($event->tenant) {
+            $tenants = $this->updateResourceInCentralDatabaseAndGetTenants($event, $syncedAttributes);
+        } else {
+            $tenants = $this->getTenantsForCentralModel($event->model);
+        }
+
+        $this->updateResourceInTenantDatabases($tenants, $event, $syncedAttributes);
+    }
+
+    protected function getTenantsForCentralModel($centralModel)
+    {
+        if (! $centralModel instanceof SyncMaster) {
+            // If we're trying to use a tenant User model instead of the central User model, for example.
+            throw new ModelNotSyncMaster(get_class($centralModel));
+        }
+
+        /** @var SyncMaster|Model $centralModel */
+
+        // Since this model is "dirty" (taken by reference from the event), it might have the tenants
+        // relationship already loaded and cached. For this reason, we refresh the relationship.
+        $centralModel->load('tenants');
+
+        return $centralModel->tenants;
+    }
+
+    protected function updateResourceInCentralDatabaseAndGetTenants($event, $syncedAttributes)
+    {
+        /** @var Model|SyncMaster $centralModel */
+        $centralModel = $event->model->getCentralModelName()
+            ::where($event->model->getGlobalIdentifierKeyName(), $event->model->getGlobalIdentifierKey())
+            ->first();
+
+        // We disable events for this call, to avoid triggering this event & listener again.
+        $event->model->getCentralModelName()::withoutEvents(function () use (&$centralModel, $syncedAttributes, $event) {
+            if ($centralModel) {
+                $centralModel->update($syncedAttributes);
+                event(new SyncedResourceChangedInForeignDatabase($event->model, null));
+            } else {
+                // If the resource doesn't exist at all in the central DB,we create
+                // the record with all attributes, not just the synced ones.
+                $centralModel = $event->model->getCentralModelName()::create($event->model->getAttributes());
+                event(new SyncedResourceChangedInForeignDatabase($event->model, null));
+            }
+        });
+
+        // If the model was just created, the mapping of the tenant to the user likely doesn't exist, so we create it.
+        $currentTenantMapping = function ($model) use ($event) {
+            return ((string) $model->pivot->tenant_id) === ((string) $event->tenant->getTenantKey());
+        };
+
+        $mappingExists = $centralModel->tenants->contains($currentTenantMapping);
+
+        if (!$mappingExists) {
+            // Here we should call TenantPivot, but we call general Pivot, so that this works
+            // even if people use their own pivot model that is not based on our TenantPivot
+            Pivot::withoutEvents(function () use ($centralModel, $event) {
+                $centralModel->tenants()->attach($event->tenant->getTenantKey());
+            });
+        }
+
+        return $centralModel->tenants->filter(function ($model) use ($currentTenantMapping) {
+            // Remove the mapping for the current tenant.
+            return !$currentTenantMapping($model);
+        });
+    }
+
+    protected function updateResourceInTenantDatabases($tenants, $event, $syncedAttributes)
+    {
+        tenancy()->runForMultiple($tenants, function ($tenant) use ($event, $syncedAttributes) {
+            // Forget instance state and find the model,
+            // again in the current tenant's context.
+
+            $eventModel = $event->model;
+
+            if ($eventModel instanceof SyncMaster) {
+                // If event model comes from central DB, we get the tenant model name to run the query
+                $localModelClass = $eventModel->getTenantModelName();
+            } else {
+                $localModelClass = get_class($eventModel);
+            }
+
+            /** @var Model|null */
+            $localModel = $localModelClass::firstWhere($event->model->getGlobalIdentifierKeyName(), $event->model->getGlobalIdentifierKey());
+
+            // Also: We're syncing attributes, not columns, which is
+            // why we're using Eloquent instead of direct DB queries.
+
+            // We disable events for this call, to avoid triggering this event & listener again.
+            $localModelClass::withoutEvents(function () use ($localModelClass, $localModel, $syncedAttributes, $eventModel, $tenant) {
+                if ($localModel) {
+                    $localModel->update($syncedAttributes);
+                } else {
+                    // When creating, we use all columns, not just the synced ones.
+                    $localModel = $localModelClass::create($eventModel->getAttributes());
+                }
+
+                event(new SyncedResourceChangedInForeignDatabase($localModel, $tenant));
+            });
+        });
+    }
+}

src/Events/SyncedResourceChangedInForeignDatabase.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Stancl\Tenancy\Events;
+
+use Stancl\Tenancy\Contracts\Syncable;
+use Stancl\Tenancy\Contracts\TenantWithDatabase;
+
+class SyncedResourceChangedInForeignDatabase
+{
+    /** @var Syncable */
+    public $model;
+
+    /** @var TenantWithDatabase|null */
+    public $tenant;
+
+    public function __construct(Syncable $model, ?TenantWithDatabase $tenant)
+    {
+        $this->model = $model;
+        $this->tenant = $tenant;
+    }
+}

src/Events/SyncedResourceSaved.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Stancl\Tenancy\Events;
+
+use Illuminate\Database\Eloquent\Model;
+use Stancl\Tenancy\Contracts\Syncable;
+use Stancl\Tenancy\Contracts\TenantWithDatabase;
+
+class SyncedResourceSaved
+{
+    /** @var Syncable|Model */
+    public $model;
+
+    /** @var TenantWithDatabase|Model|null */
+    public $tenant;
+
+    public function __construct(Syncable $model, ?TenantWithDatabase $tenant)
+    {
+        $this->model = $model;
+        $this->tenant = $tenant;
+    }
+}

src/Exceptions/ModelNotSyncMaster.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Stancl\Tenancy\Exceptions;
+
+use Exception;
+
+class ModelNotSyncMaster extends Exception
+{
+    public function __construct(string $class)
+    {
+        parent::__construct("Model of $class class is not an SyncMaster model. Make sure you're using the central model to make changes to synced resouces when you're in the central context");
+    }
+}

src/Tenancy.php

@@ -77,7 +77,7 @@ class Tenancy
      * Run a callback for multiple tenants.
      * More performant than running $tenant->run() one by one.
      *
-     * @param Tenant[]|\Illuminate\Support\Collection|string[]|null $tenants
+     * @param Tenant[]|\Traversable|string[]|null $tenants
      * @param callable $callback
      * @return void
      */

src/UniqueIDGenerators/UUIDGenerator.php

@@ -6,11 +6,10 @@ namespace Stancl\Tenancy\UniqueIDGenerators;
 
 use Ramsey\Uuid\Uuid;
 use Stancl\Tenancy\Contracts\UniqueIdentifierGenerator;
-use Stancl\Tenancy\Database\Models\Tenant;
 
 class UUIDGenerator implements UniqueIdentifierGenerator
 {
-    public static function generate(Tenant $tenant): string
+    public static function generate($resource): string
     {
         return Uuid::uuid4()->toString();
     }

tests/Etc/synced_resource_migrations/2020_05_11_000002_create_tenant_users_table.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+class CreateTenantUsersTable extends Migration
+{
+    /**
+     * Run the migrations.
+     *
+     * @return void
+     */
+    public function up()
+    {
+        Schema::create('tenant_users', function (Blueprint $table) {
+            $table->increments('id');
+            $table->string('tenant_id');
+            $table->string('global_user_id');
+
+            $table->unique(['tenant_id', 'global_user_id']);
+
+            $table->foreign('tenant_id')->references('id')->on('tenants')->onUpdate('cascade')->onDelete('cascade');
+            $table->foreign('global_user_id')->references('global_id')->on('users')->onUpdate('cascade')->onDelete('cascade');
+        });
+    }
+
+    public function down()
+    {
+        Schema::dropIfExists('tenant_users');
+    }
+}

tests/Etc/synced_resource_migrations/users/2020_05_11_000001_create_users_table.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+class CreateUsersTable extends Migration
+{
+    /**
+     * Run the migrations.
+     *
+     * @return void
+     */
+    public function up()
+    {
+        Schema::create('users', function (Blueprint $table) {
+            $table->increments('id');
+            $table->string('global_id')->unique();
+            $table->string('name');
+            $table->string('email');
+            $table->string('password');
+
+            $table->string('role');
+        });
+    }
+
+    public function down()
+    {
+        Schema::dropIfExists('users');
+    }
+}

tests/v3/ResourceSyncingTest.php

@@ -0,0 +1,640 @@
+<?php
+
+namespace Stancl\Tenancy\Tests\v3;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsToMany;
+use Illuminate\Events\CallQueuedListener;
+use Illuminate\Support\Facades\Event;
+use Illuminate\Support\Facades\Queue;
+use Stancl\Tenancy\Contracts\Syncable;
+use Stancl\Tenancy\Contracts\SyncMaster;
+use Stancl\Tenancy\Database\Models\Concerns\CentralConnection;
+use Stancl\Tenancy\Database\Models\Concerns\ResourceSyncing;
+use Stancl\Tenancy\Database\Models;
+use Stancl\Tenancy\Database\Models\TenantPivot;
+use Stancl\Tenancy\Events\Listeners\BootstrapTenancy;
+use Stancl\Tenancy\Events\Listeners\JobPipeline;
+use Stancl\Tenancy\Events\Listeners\RevertToCentralContext;
+use Stancl\Tenancy\Events\Listeners\UpdateSyncedResource;
+use Stancl\Tenancy\Events\SyncedResourceChangedInForeignDatabase;
+use Stancl\Tenancy\Events\SyncedResourceSaved;
+use Stancl\Tenancy\Events\TenancyEnded;
+use Stancl\Tenancy\Events\TenancyInitialized;
+use Stancl\Tenancy\Events\TenantCreated;
+use Stancl\Tenancy\Exceptions\ModelNotSyncMaster;
+use Stancl\Tenancy\Jobs\CreateDatabase;
+use Stancl\Tenancy\TenancyBootstrappers\DatabaseTenancyBootstrapper;
+use Stancl\Tenancy\Tests\TestCase;
+
+class ResourceSyncingTest extends TestCase
+{
+    public function setUp(): void
+    {
+        parent::setUp();
+
+        config(['tenancy.bootstrappers' => [
+            DatabaseTenancyBootstrapper::class,
+        ]]);
+
+        Event::listen(TenantCreated::class, JobPipeline::make([CreateDatabase::class])->send(function (TenantCreated $event) {
+            return $event->tenant;
+        })->toListener());
+
+        Event::listen(TenancyInitialized::class, BootstrapTenancy::class);
+        Event::listen(TenancyEnded::class, RevertToCentralContext::class);
+
+        UpdateSyncedResource::$shouldQueue = false; // global state cleanup
+        Event::listen(SyncedResourceSaved::class, UpdateSyncedResource::class);
+
+        $this->artisan('migrate', [
+            '--path' => [
+                __DIR__ . '/../Etc/synced_resource_migrations',
+                __DIR__ . '/../Etc/synced_resource_migrations/users'
+            ],
+            '--realpath' => true,
+        ])->assertExitCode(0);
+    }
+
+    protected function migrateTenants()
+    {
+        $this->artisan('tenants:migrate', [
+            '--path' => __DIR__ . '/../Etc/synced_resource_migrations/users',
+            '--realpath' => true,
+        ])->assertExitCode(0);
+    }
+
+    /** @test */
+    public function an_event_is_triggered_when_a_synced_resource_is_changed()
+    {
+        Event::fake([SyncedResourceSaved::class]);
+
+        $user = User::create([
+            'name' => 'Foo',
+            'email' => 'foo@email.com',
+            'password' => 'secret',
+            'global_id' => 'foo',
+            'role' => 'foo',
+        ]);
+
+        Event::assertDispatched(SyncedResourceSaved::class, function (SyncedResourceSaved $event) use ($user) {
+            return $event->model === $user;
+        });
+    }
+
+    /** @test */
+    public function only_the_synced_columns_are_updated_in_the_central_db()
+    {
+        // Create user in central DB
+        $user = CentralUser::create([
+            'global_id' => 'acme',
+            'name' => 'John Doe',
+            'email' => 'john@localhost',
+            'password' => 'secret',
+            'role' => 'superadmin', // unsynced
+        ]);
+
+        $tenant = Tenant::create();
+        $this->migrateTenants();
+
+        tenancy()->initialize($tenant);
+
+        // Create the same user in tenant DB
+        $user = User::create([
+            'global_id' => 'acme',
+            'name' => 'John Doe',
+            'email' => 'john@localhost',
+            'password' => 'secret',
+            'role' => 'commenter', // unsynced
+        ]);
+
+        // Update user in tenant DB
+        $user->update([
+            'role' => 'admin', // unsynced
+            'name' => 'John Foo', // synceed
+            'email' => 'john@foreignhost', // synceed
+        ]);
+
+        // Assert new values
+        $this->assertEquals([
+            'id' => 1,
+            'global_id' => 'acme',
+            'name' => 'John Foo',
+            'email' => 'john@foreignhost',
+            'password' => 'secret',
+            'role' => 'admin',
+        ], $user->getAttributes());
+
+        tenancy()->end();
+
+        // Assert changes bubbled up
+        $this->assertEquals([
+            'id' => 1,
+            'global_id' => 'acme',
+            'name' => 'John Foo', // synced
+            'email' => 'john@foreignhost', // synced
+            'password' => 'secret', // no changes
+            'role' => 'superadmin', // unsynced
+        ], User::first()->getAttributes());
+    }
+
+    /** @test */
+    public function creating_the_resource_in_tenant_database_creates_it_in_central_database_and_creates_the_mapping()
+    {
+        // Assert no user in central DB
+        $this->assertCount(0, User::all());
+
+        $tenant = Tenant::create();
+        $this->migrateTenants();
+
+        tenancy()->initialize($tenant);
+
+        // Create the same user in tenant DB
+        User::create([
+            'global_id' => 'acme',
+            'name' => 'John Doe',
+            'email' => 'john@localhost',
+            'password' => 'secret',
+            'role' => 'commenter', // unsynced
+        ]);
+
+        tenancy()->end();
+
+        // Asset user was created
+        $this->assertSame('acme', CentralUser::first()->global_id);
+        $this->assertSame('commenter', CentralUser::first()->role);
+
+        // Assert mapping was created
+        $this->assertCount(1, CentralUser::first()->tenants);
+
+        // Assert role change doesn't cascade
+        CentralUser::first()->update(['role' => 'central superadmin']);
+        tenancy()->initialize($tenant);
+        $this->assertSame('commenter', User::first()->role);
+    }
+
+    /** @test */
+    public function trying_to_update_synced_resources_from_central_context_using_tenant_models_results_in_an_exception()
+    {
+        $this->creating_the_resource_in_tenant_database_creates_it_in_central_database_and_creates_the_mapping();
+
+        tenancy()->end();
+        $this->assertFalse(tenancy()->initialized);
+
+        $this->expectException(ModelNotSyncMaster::class);
+        User::first()->update(['role' => 'foobar']);
+    }
+
+    /** @test */
+    public function attaching_a_tenant_to_the_central_resource_triggers_a_pull_from_the_tenant_db()
+    {
+        $centralUser = CentralUser::create([
+            'global_id' => 'acme',
+            'name' => 'John Doe',
+            'email' => 'john@localhost',
+            'password' => 'secret',
+            'role' => 'commenter', // unsynced
+        ]);
+
+        $tenant = Tenant::create([
+            'id' => 't1',
+        ]);
+        $this->migrateTenants();
+
+        $tenant->run(function () {
+            $this->assertCount(0, User::all());
+        });
+
+        $centralUser->tenants()->attach('t1');
+
+        $tenant->run(function () {
+            $this->assertCount(1, User::all());
+        });
+    }
+
+    /** @test */
+    public function attaching_users_to_tenants_DOES_NOT_DO_ANYTHING()
+    {
+        $centralUser = CentralUser::create([
+            'global_id' => 'acme',
+            'name' => 'John Doe',
+            'email' => 'john@localhost',
+            'password' => 'secret',
+            'role' => 'commenter', // unsynced
+        ]);
+
+        $tenant = Tenant::create([
+            'id' => 't1',
+        ]);
+        $this->migrateTenants();
+
+        $tenant->run(function () {
+            $this->assertCount(0, User::all());
+        });
+
+        // The child model is inaccessible in the Pivot Model, so we can't fire any events.
+        $tenant->users()->attach($centralUser);
+
+        $tenant->run(function () {
+            // Still zero
+            $this->assertCount(0, User::all());
+        });
+    }
+
+    /** @test */
+    public function resources_are_synced_only_to_workspaces_that_have_the_resource()
+    {
+        $centralUser = CentralUser::create([
+            'global_id' => 'acme',
+            'name' => 'John Doe',
+            'email' => 'john@localhost',
+            'password' => 'secret',
+            'role' => 'commenter', // unsynced
+        ]);
+
+        $t1 = Tenant::create([
+            'id' => 't1',
+        ]);
+
+        $t2 = Tenant::create([
+            'id' => 't2',
+        ]);
+
+        $t3 = Tenant::create([
+            'id' => 't3',
+        ]);
+        $this->migrateTenants();
+
+        $centralUser->tenants()->attach('t1');
+        $centralUser->tenants()->attach('t2');
+        // t3 is not attached
+
+        $t1->run(function () {
+            // assert user exists
+            $this->assertCount(1, User::all());
+        });
+
+        $t2->run(function () {
+            // assert user exists
+            $this->assertCount(1, User::all());
+        });
+
+        $t3->run(function () {
+            // assert user does NOT exist
+            $this->assertCount(0, User::all());
+        });
+    }
+
+    /** @test */
+    public function when_a_resource_exists_in_other_tenant_dbs_but_is_CREATED_in_a_tenant_db_the_synced_columns_are_updated_in_the_other_dbs()
+    {
+        // create shared resource
+        $centralUser = CentralUser::create([
+            'global_id' => 'acme',
+            'name' => 'John Doe',
+            'email' => 'john@localhost',
+            'password' => 'secret',
+            'role' => 'commenter', // unsynced
+        ]);
+
+        $t1 = Tenant::create([
+            'id' => 't1',
+        ]);
+        $t2 = Tenant::create([
+            'id' => 't2',
+        ]);
+        $this->migrateTenants();
+
+        // Copy (cascade) user to t1 DB
+        $centralUser->tenants()->attach('t1');
+
+        $t2->run(function () {
+            // Create user with the same global ID in t2 database
+            User::create([
+                'global_id' => 'acme',
+                'name' => 'John Foo', // changed
+                'email' => 'john@foo', // changed
+                'password' => 'secret',
+                'role' => 'superadmin', // unsynced
+            ]);
+        });
+
+        $centralUser = CentralUser::first();
+        $this->assertSame('John Foo', $centralUser->name); // name changed
+        $this->assertSame('john@foo', $centralUser->email); // email changed
+        $this->assertSame('commenter', $centralUser->role); // role didn't change
+
+        $t1->run(function () {
+            $user = User::first();
+            $this->assertSame('John Foo', $user->name); // name changed
+            $this->assertSame('john@foo', $user->email); // email changed
+            $this->assertSame('commenter', $user->role); // role didn't change, i.e. is the same as from the original copy from central
+        });
+    }
+
+    /** @test */
+    public function the_synced_columns_are_updated_in_other_tenant_dbs_where_the_resource_exists()
+    {
+        // create shared resource
+        $centralUser = CentralUser::create([
+            'global_id' => 'acme',
+            'name' => 'John Doe',
+            'email' => 'john@localhost',
+            'password' => 'secret',
+            'role' => 'commenter', // unsynced
+        ]);
+
+        $t1 = Tenant::create([
+            'id' => 't1',
+        ]);
+        $t2 = Tenant::create([
+            'id' => 't2',
+        ]);
+        $t3 = Tenant::create([
+            'id' => 't3',
+        ]);
+        $this->migrateTenants();
+
+        // Copy (cascade) user to t1 DB
+        $centralUser->tenants()->attach('t1');
+        $centralUser->tenants()->attach('t2');
+        $centralUser->tenants()->attach('t3');
+
+        $t3->run(function () {
+            User::first()->update([
+                'name' => 'John 3',
+                'role' => 'employee', // unsynced
+            ]);
+
+            $this->assertSame('employee', User::first()->role);
+        });
+
+        // Check that change was cascaded to other tenants
+        $t1->run($check = function () {
+            $user = User::first();
+
+            $this->assertSame('John 3', $user->name); // synced
+            $this->assertSame('commenter', $user->role); // unsynced
+        });
+        $t2->run($check);
+
+        // Check that change bubbled up to central DB
+        $this->assertSame(1, CentralUser::count());
+        $centralUser = CentralUser::first();
+        $this->assertSame('John 3', $centralUser->name); // synced
+        $this->assertSame('commenter', $centralUser->role); // unsynced
+    }
+
+    /** @test */
+    public function global_id_is_generated_using_id_generator_when_its_not_supplied()
+    {
+        $user = CentralUser::create([
+            'name' => 'John Doe',
+            'email' => 'john@doe',
+            'password' => 'secret',
+            'role' => 'employee',
+        ]);
+
+        $this->assertNotNull($user->global_id);
+    }
+
+    /** @test */
+    public function when_the_resource_doesnt_exist_in_the_tenant_db_non_synced_columns_will_cascade_too()
+    {
+        $centralUser = CentralUser::create([
+            'name' => 'John Doe',
+            'email' => 'john@doe',
+            'password' => 'secret',
+            'role' => 'employee',
+        ]);
+
+        $t1 = Tenant::create([
+            'id' => 't1',
+        ]);
+
+        $this->migrateTenants();
+
+        $centralUser->tenants()->attach('t1');
+
+        $t1->run(function () {
+            $this->assertSame('employee', User::first()->role);
+        });
+    }
+
+    /** @test */
+    public function when_the_resource_doesnt_exist_in_the_central_db_non_synced_columns_will_bubble_up_too()
+    {
+        $t1 = Tenant::create([
+            'id' => 't1',
+        ]);
+
+        $this->migrateTenants();
+
+        $t1->run(function () {
+            User::create([
+                'name' => 'John Doe',
+                'email' => 'john@doe',
+                'password' => 'secret',
+                'role' => 'employee',
+            ]);
+        });
+
+        $this->assertSame('employee', CentralUser::first()->role);
+    }
+
+    /** @test */
+    public function the_listener_can_be_queued()
+    {
+        Queue::fake();
+        UpdateSyncedResource::$shouldQueue = true;
+
+        $t1 = Tenant::create([
+            'id' => 't1',
+        ]);
+
+        $this->migrateTenants();
+
+        Queue::assertNothingPushed();
+
+        $t1->run(function () {
+            User::create([
+                'name' => 'John Doe',
+                'email' => 'john@doe',
+                'password' => 'secret',
+                'role' => 'employee',
+            ]);
+        });
+
+        Queue::assertPushed(CallQueuedListener::class, function (CallQueuedListener $job) {
+            return $job->class === UpdateSyncedResource::class;
+        });
+    }
+
+    /** @test */
+    public function an_event_is_fired_for_all_touched_resources()
+    {
+        Event::fake([SyncedResourceChangedInForeignDatabase::class]);
+
+        // create shared resource
+        $centralUser = CentralUser::create([
+            'global_id' => 'acme',
+            'name' => 'John Doe',
+            'email' => 'john@localhost',
+            'password' => 'secret',
+            'role' => 'commenter', // unsynced
+        ]);
+
+        $t1 = Tenant::create([
+            'id' => 't1',
+        ]);
+        $t2 = Tenant::create([
+            'id' => 't2',
+        ]);
+        $t3 = Tenant::create([
+            'id' => 't3',
+        ]);
+        $this->migrateTenants();
+
+        // Copy (cascade) user to t1 DB
+        $centralUser->tenants()->attach('t1');
+        Event::assertDispatched(SyncedResourceChangedInForeignDatabase::class, function (SyncedResourceChangedInForeignDatabase $event) {
+            return $event->tenant->getTenantKey() === 't1';
+        });
+        
+        $centralUser->tenants()->attach('t2');
+        Event::assertDispatched(SyncedResourceChangedInForeignDatabase::class, function (SyncedResourceChangedInForeignDatabase $event) {
+            return $event->tenant->getTenantKey() === 't2';
+        });
+
+        $centralUser->tenants()->attach('t3');
+        Event::assertDispatched(SyncedResourceChangedInForeignDatabase::class, function (SyncedResourceChangedInForeignDatabase $event) {
+            return $event->tenant->getTenantKey() === 't3';
+        });
+
+        // Assert no event for central
+        Event::assertNotDispatched(SyncedResourceChangedInForeignDatabase::class, function (SyncedResourceChangedInForeignDatabase $event) {
+            return $event->tenant === null;
+        });
+
+        // Flush
+        Event::fake([SyncedResourceChangedInForeignDatabase::class]);
+
+        $t3->run(function () {
+            User::first()->update([
+                'name' => 'John 3',
+                'role' => 'employee', // unsynced
+            ]);
+
+            $this->assertSame('employee', User::first()->role);
+        });
+
+        Event::assertDispatched(SyncedResourceChangedInForeignDatabase::class, function (SyncedResourceChangedInForeignDatabase $event) {
+            return optional($event->tenant)->getTenantKey() === 't1';
+        });
+        Event::assertDispatched(SyncedResourceChangedInForeignDatabase::class, function (SyncedResourceChangedInForeignDatabase $event) {
+            return optional($event->tenant)->getTenantKey() === 't2';
+        });
+
+        // Assert NOT dispatched in t3
+        Event::assertNotDispatched(SyncedResourceChangedInForeignDatabase::class, function (SyncedResourceChangedInForeignDatabase $event) {
+            return optional($event->tenant)->getTenantKey() === 't3';
+        });
+
+        // Assert dispatched in central
+        Event::assertDispatched(SyncedResourceChangedInForeignDatabase::class, function (SyncedResourceChangedInForeignDatabase $event) {
+            return $event->tenant === null;
+        });
+
+        // todo update in global
+    }
+}
+
+class Tenant extends Models\Tenant
+{
+    public function users()
+    {
+        return $this->belongsToMany(CentralUser::class, 'tenant_users', 'tenant_id', 'global_user_id')
+            ->using(TenantPivot::class);
+    }
+}
+
+class CentralUser extends Model implements SyncMaster
+{
+    use ResourceSyncing, CentralConnection;
+
+    protected $guarded = [];
+    public $timestamps = false;
+    public $table = 'users';
+
+    public function tenants(): BelongsToMany
+    {
+        return $this->belongsToMany(Tenant::class, 'tenant_users', 'global_user_id', 'tenant_id')
+            ->using(TenantPivot::class);
+    }
+
+    public function getTenantModelName(): string
+    {
+        return User::class;
+    }
+
+    public function getTenantIdColumnInMapTable(): string
+    {
+        return 'tenant_id';
+    }
+
+    public function getGlobalIdentifierKey(): string
+    {
+        return $this->getAttribute($this->getGlobalIdentifierKeyName());
+    }
+
+    public function getGlobalIdentifierKeyName(): string
+    {
+        return 'global_id';
+    }
+
+    public function getCentralModelName(): string
+    {
+        return static::class;
+    }
+
+    public function getSyncedAttributeNames(): array
+    {
+        return [
+            'name',
+            'password',
+            'email',
+        ];
+    }
+}
+
+class User extends Model implements Syncable
+{
+    use ResourceSyncing;
+
+    protected $guarded = [];
+    public $timestamps = false;
+
+    public function getGlobalIdentifierKey(): string
+    {
+        return $this->getAttribute($this->getGlobalIdentifierKeyName());
+    }
+
+    public function getGlobalIdentifierKeyName(): string
+    {
+        return 'global_id';
+    }
+
+    public function getCentralModelName(): string
+    {
+        return CentralUser::class;
+    }
+
+    public function getSyncedAttributeNames(): array
+    {
+        return [
+            'name',
+            'password',
+            'email',
+        ];
+    }
+}