Add support for stripe-style identifiers on existing models with UUIDs (#5548)

This is a partial implementation to begin moving towards stripe-style
identifiers for resources in the system. Any models with an existing
`uuid` column can easily be updated to return an identifier in the
format of `prfx_xyz` where `prfx` is a four character prefix, and `xyz`
is the UUID, encoded using base-32.

These are quite easy to use within the API layer because we just need to
do one quick transformation to extract the UUID for those models. This
PR implements that logic for servers in the `SubstituteClientBindings`
logic.

A future PR will need to come through and handle identifiers for models
that _don't_ currently use UUIDs for reference that we want to expose to
clients. In those cases it is easier to just generate base-32 encoded
UUID7s that get stored in the database and indexed. They follow the same
base approach, but you don't need to do any transformations in the code
(other than stripping the prefix, unless we decide to store the prefix).

There is also now a `PTERODACTYL_USE_SERVER_IDENTIFIERS` environment
variable, that when set to true, updates the front-end and API response
to use this new identifier in place of the `uuidShort` value.

Author: DaneEveritt

.php-cs-fixer.dist.php

@@ -47,6 +47,7 @@
                 'var',
             ],
         ],
+        'phpdoc_no_alias_tag' => false,
         // 'random_api_migration' => true,
         'ternary_to_null_coalescing' => true,
         'yoda_style' => [

app/Contracts/Models/Identifiable.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Pterodactyl\Contracts\Models;
+
+use Illuminate\Database\Eloquent\Builder;
+
+interface Identifiable
+{
+    public function scopeWhereIdentifier(Builder $builder, string $identifier): void;
+}

app/Http/Middleware/Api/Client/SubstituteClientBindings.php

@@ -15,7 +15,13 @@ public function handle($request, \Closure $next): mixed
         // Override default behavior of the model binding to use a specific table
         // column rather than the default 'id'.
         $this->router->bind('server', function ($value) {
-            return Server::query()->where(strlen($value) === 8 ? 'uuidShort' : 'uuid', $value)->firstOrFail();
+            return Server::query()
+                ->when(
+                    str_starts_with($value, 'serv_'),
+                    fn ($builder) => $builder->whereIdentifier($value),
+                    fn ($builder) => $builder->where(strlen($value) === 8 ? 'uuidShort' : 'uuid', $value)
+                )
+                ->firstOrFail();
         });
 
         $this->router->bind('user', function ($value, $route) {

app/Models/ActivityLog.php

@@ -7,9 +7,11 @@
 use Pterodactyl\Events\ActivityLogged;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\MassPrunable;
+use Pterodactyl\Contracts\Models\Identifiable;
 use Illuminate\Database\Eloquent\Relations\HasOne;
 use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Database\Eloquent\Relations\MorphTo;
+use Pterodactyl\Models\Traits\HasRealtimeIdentifier;
 use Illuminate\Database\Eloquent\Model as IlluminateModel;
 
 /**
@@ -48,9 +50,11 @@
  *
  * @mixin \Eloquent
  */
-class ActivityLog extends Model
+#[Attributes\Identifiable('actl')]
+class ActivityLog extends Model implements Identifiable
 {
     use MassPrunable;
+    use HasRealtimeIdentifier;
 
     public const RESOURCE_NAME = 'activity_log';
 

app/Models/Attributes/Identifiable.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Pterodactyl\Models\Attributes;
+
+#[\Attribute(\Attribute::TARGET_CLASS)]
+readonly class Identifiable
+{
+    public function __construct(public string $prefix, public string $column = 'uuid')
+    {
+    }
+}

app/Models/Backup.php

@@ -3,6 +3,8 @@
 namespace Pterodactyl\Models;
 
 use Illuminate\Database\Eloquent\SoftDeletes;
+use Pterodactyl\Contracts\Models\Identifiable;
+use Pterodactyl\Models\Traits\HasRealtimeIdentifier;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 
@@ -25,11 +27,13 @@
  * @property Server $server
  * @property \Pterodactyl\Models\AuditLog[] $audits
  */
-class Backup extends Model
+#[Attributes\Identifiable('bkup')]
+class Backup extends Model implements Identifiable
 {
     /** @use HasFactory<\Database\Factories\BackupFactory> */
     use HasFactory;
     use SoftDeletes;
+    use HasRealtimeIdentifier;
 
     public const RESOURCE_NAME = 'backup';
 

app/Models/Egg.php

@@ -2,7 +2,9 @@
 
 namespace Pterodactyl\Models;
 
+use Pterodactyl\Contracts\Models\Identifiable;
 use Illuminate\Database\Eloquent\Relations\HasMany;
+use Pterodactyl\Models\Traits\HasRealtimeIdentifier;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 
@@ -47,10 +49,12 @@
  * @property Egg|null $scriptFrom
  * @property Egg|null $configFrom
  */
-class Egg extends Model
+#[Attributes\Identifiable('eegg')]
+class Egg extends Model implements Identifiable
 {
     /** @use HasFactory<\Database\Factories\EggFactory> */
     use HasFactory;
+    use HasRealtimeIdentifier;
 
     /**
      * The resource name for this model when it is transformed into an

app/Models/Mount.php

@@ -3,6 +3,8 @@
 namespace Pterodactyl\Models;
 
 use Illuminate\Validation\Rules\NotIn;
+use Pterodactyl\Contracts\Models\Identifiable;
+use Pterodactyl\Models\Traits\HasRealtimeIdentifier;
 use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 
 /**
@@ -18,8 +20,11 @@
  * @property \Pterodactyl\Models\Node[]|\Illuminate\Database\Eloquent\Collection $nodes
  * @property \Pterodactyl\Models\Server[]|\Illuminate\Database\Eloquent\Collection $servers
  */
-class Mount extends Model
+#[Attributes\Identifiable('moun')]
+class Mount extends Model implements Identifiable
 {
+    use HasRealtimeIdentifier;
+
     /**
      * The resource name for this model when it is transformed into an
      * API representation using fractal.

app/Models/Node.php

@@ -7,7 +7,9 @@
 use Illuminate\Container\Container;
 use Illuminate\Notifications\Notifiable;
 use Illuminate\Contracts\Encryption\Encrypter;
+use Pterodactyl\Contracts\Models\Identifiable;
 use Illuminate\Database\Eloquent\Relations\HasMany;
+use Pterodactyl\Models\Traits\HasRealtimeIdentifier;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Relations\HasManyThrough;
@@ -40,11 +42,13 @@
  * @property \Pterodactyl\Models\Server[]|\Illuminate\Database\Eloquent\Collection $servers
  * @property \Pterodactyl\Models\Allocation[]|\Illuminate\Database\Eloquent\Collection $allocations
  */
-class Node extends Model
+#[Attributes\Identifiable('node')]
+class Node extends Model implements Identifiable
 {
     /** @use HasFactory<\Database\Factories\NodeFactory> */
     use HasFactory;
     use Notifiable;
+    use HasRealtimeIdentifier;
 
     /**
      * The resource name for this model when it is transformed into an

app/Models/Server.php

@@ -5,8 +5,10 @@
 use Illuminate\Notifications\Notifiable;
 use Illuminate\Database\Query\JoinClause;
 use Znck\Eloquent\Traits\BelongsToThrough;
+use Pterodactyl\Contracts\Models\Identifiable;
 use Illuminate\Database\Eloquent\Relations\HasOne;
 use Illuminate\Database\Eloquent\Relations\HasMany;
+use Pterodactyl\Models\Traits\HasRealtimeIdentifier;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Relations\MorphToMany;
@@ -103,19 +105,20 @@
  *
  * @mixin \Eloquent
  */
-class Server extends Model
+#[Attributes\Identifiable('serv')]
+class Server extends Model implements Identifiable
 {
     /** @use HasFactory<\Database\Factories\ServerFactory> */
     use HasFactory;
     use BelongsToThrough;
     use Notifiable;
+    use HasRealtimeIdentifier;
 
     /**
      * The resource name for this model when it is transformed into an
      * API representation using fractal.
      */
     public const RESOURCE_NAME = 'server';
-
     public const STATUS_INSTALLING = 'installing';
     public const STATUS_INSTALL_FAILED = 'install_failed';
     public const STATUS_REINSTALL_FAILED = 'reinstall_failed';