Added Custom GUID support.

FAQ.md

@@ -947,3 +947,68 @@ In my docker host the group id for `video` is `44` and for `render` is `105`. ch
 file to match your setup.
 
 Note: the tip about adding the group_add came from the user `binarypancakes` in discord.
+
+---
+
+### Advanced: How to extend the GUID parser to support more GUIDs or custom ones?
+
+You can extend the parser by creating new file at `/config/config/guid.yaml` with the following content.
+
+```yaml
+# The version of the guid file. right now in beta so it's 0.0. not required to be present.
+version: 0.0
+
+# The key must be in lower case. and it's an array.
+guids:
+    -   type: string                            # must be exactly string do not change it.
+        name: guid_mydb                         # the name must start with guid_ with no spaces and lower case.
+        description: "My custom database guid"  # description of the guid.
+        # Validator object. to validate the guid.
+        validator:
+            pattern: /^[0-9\/]+$/i  # regex pattern to match the guid. The pattern must also support / being in the guid. as we use the same object to generate relative guid.
+            example: "(number)"     # example of the guid.
+            tests:
+                valid:
+                    - "1234567"     # valid guid examples.
+                invalid:
+                    - "1234567a"    # invalid guid examples.
+                    - "a111234567"  # invalid guid examples.
+
+# Extend Plex client to support the new guid.
+plex:
+    -   legacy: true  # Tag the mapper as legacy GUID for mapping.
+        # Required map object. to map the new guid to WatchState guid.
+        map:
+            from: com.plexapp.agents.foo # map.from this string.
+            to: guid_mydb                # map.to this guid.
+        # (Optional) Replace helper. Sometimes you need to replace the guid identifier to another.
+        # The replacement happens before the mapping, so if you replace the guid identifier, you should also
+        # update the map.from to match the new identifier.
+        replace:
+            from: com.plexapp.agents.foobar://  # Replace from this string
+            to: com.plexapp.agents.foo://       # Into this string.
+
+# Extend Jellyfin client to support the new guid.
+jellyfin:
+    # Required map object. to map the new guid to WatchState guid.
+    -   map:
+            from: foo     # map.from this string.
+            to: guid_mydb # map.to this guid.
+
+# Extend Emby client to support the new guid.
+emby:
+    # Required map object. to map the new guid to WatchState guid.
+    -   map:
+            from: foo     # map.from this string.
+            to: guid_mydb # map.to this guid.
+```
+
+As you can see from the config, it's roughly how we expected it to be. The `guids` array is where you define your new
+guids. The `plex`, `jellyfin` and `emby` objects are where you map the new guid to the WatchState guid.
+
+Everything in this file should be in lower case. If error occurs, the tool will log a warning and ignore the guid,
+By default, we only show `ERROR` levels in log file, You can lower it by setting `WS_LOGGER_FILE_LEVEL` environment variable
+to `WARNING`.
+
+If you added or removed a guid from the `guid.yaml` file, you should run `system:reindex --force-reindex` command to update the
+database indexes with the new guids.

config/config.php

@@ -81,6 +81,11 @@
         ],
     ];
 
+    $config['guid'] = [
+        'version' => '0.0',
+        'file' => fixPath(env('WS_GUID_FILE', ag($config, 'path') . '/config/guid.yaml')),
+    ];
+
     $config['backends_file'] = fixPath(env('WS_BACKENDS_FILE', ag($config, 'path') . '/config/servers.yaml'));
 
     date_default_timezone_set(ag($config, 'tz', 'UTC'));

src/API/System/Guids.php

@@ -5,10 +5,12 @@
 namespace App\API\System;
 
 use App\Libs\Attributes\Route\Get;
+use App\Libs\Container;
 use App\Libs\Enums\Http\Status;
 use App\Libs\Guid;
 use Psr\Http\Message\ResponseInterface as iResponse;
 use Psr\Http\Message\ServerRequestInterface as iRequest;
+use Psr\Log\LoggerInterface;
 
 final class Guids
 {
@@ -19,6 +21,7 @@ public function __invoke(iRequest $request): iResponse
     {
         $list = [];
 
+        Guid::setLogger(Container::get(LoggerInterface::class));
         $validator = Guid::getValidators();
 
         foreach (Guid::getSupported() as $guid => $type) {

src/Backends/Jellyfin/JellyfinGuid.php

@@ -6,18 +6,25 @@
 
 use App\Backends\Common\Context;
 use App\Backends\Common\GuidInterface as iGuid;
+use App\Libs\Config;
+use App\Libs\Exceptions\Backends\InvalidArgumentException;
 use App\Libs\Guid;
 use Psr\Log\LoggerInterface;
+use Symfony\Component\Yaml\Exception\ParseException;
+use Symfony\Component\Yaml\Yaml;
 use Throwable;
 
 class JellyfinGuid implements iGuid
 {
-    private const array GUID_MAPPER = [
+    private string $type;
+
+    private array $guidMapper = [
         'imdb' => Guid::GUID_IMDB,
         'tmdb' => Guid::GUID_TMDB,
         'tvdb' => Guid::GUID_TVDB,
         'tvmaze' => Guid::GUID_TVMAZE,
         'tvrage' => Guid::GUID_TVRAGE,
+        'anidb' => Guid::GUID_ANIDB,
         'ytinforeader' => Guid::GUID_YOUTUBE,
         'cmdb' => Guid::GUID_CMDB,
     ];
@@ -31,6 +38,149 @@ class JellyfinGuid implements iGuid
      */
     public function __construct(protected LoggerInterface $logger)
     {
+        $this->type = str_contains(static::class, 'EmbyGuid') ? 'emby' : 'jellyfin';
+
+        $file = Config::get('guid.file', null);
+
+        try {
+            if (null !== $file && true === file_exists($file)) {
+                $this->parseGUIDFile($file);
+            }
+        } catch (Throwable $e) {
+            $this->logger->error("{class}: Failed to read or parse '{guid}' file. Error '{error}'.", [
+                'class' => afterLast(static::class, '\\'),
+                'guid' => $file,
+                'error' => $e->getMessage(),
+                'exception' => [
+                    'message' => $e->getMessage(),
+                    'code' => $e->getCode(),
+                    'file' => $e->getFile(),
+                    'line' => $e->getLine(),
+                    'trace' => $e->getTrace(),
+                ],
+            ]);
+        }
+    }
+
+    /**
+     * Extends WatchState GUID parsing to include external GUIDs.
+     *
+     * @param string $file The path to the external GUID mapping file.
+     *
+     * @throws InvalidArgumentException if the file does not exist or is not readable.
+     * @throws InvalidArgumentException if the GUIDs file cannot be parsed.
+     * @throws InvalidArgumentException if the file version is not supported.
+     */
+    public function parseGUIDFile(string $file): void
+    {
+        if (false === file_exists($file) || false === is_readable($file)) {
+            throw new InvalidArgumentException(r("The file '{file}' does not exist or is not readable.", [
+                'file' => $file,
+            ]));
+        }
+
+        if (filesize($file) < 1) {
+            $this->logger->info("The external GUID mapping file '{file}' is empty.", ['file' => $file]);
+            return;
+        }
+
+        try {
+            $yaml = Yaml::parseFile($file);
+            if (false === is_array($yaml)) {
+                throw new InvalidArgumentException(r("The GUIDs file '{file}' is not an array.", [
+                    'file' => $file,
+                ]));
+            }
+        } catch (ParseException $e) {
+            throw new InvalidArgumentException(r("Failed to parse GUIDs file. Error '{error}'.", [
+                'error' => $e->getMessage(),
+            ]), code: (int)$e->getCode(), previous: $e);
+        }
+
+        $supported = array_keys(Guid::getSupported());
+        $supportedVersion = Config::get('guid.version', '0.0');
+        $guidVersion = (string)ag($yaml, 'version', $supportedVersion);
+
+        if (true === version_compare($supportedVersion, $guidVersion, '<')) {
+            throw new InvalidArgumentException(r("Unsupported file version '{version}'. Expecting '{supported}'.", [
+                'version' => $guidVersion,
+                'supported' => $supportedVersion,
+            ]));
+        }
+
+        $mapping = ag($yaml, $this->type, []);
+
+        if (false === is_array($mapping)) {
+            throw new InvalidArgumentException(r("The GUIDs file '{file}' {type} sub key is not an array.", [
+                'type' => $this->type,
+                'file' => $file,
+            ]));
+        }
+
+        if (count($mapping) < 1) {
+            return;
+        }
+
+        foreach ($mapping as $key => $map) {
+            if (false === is_array($map)) {
+                $this->logger->warning("Ignoring '{type}.{key}'. Value must be an object. '{given}' is given.", [
+                    'key' => $key,
+                    'type' => $this->type,
+                    'given' => get_debug_type($map),
+                ]);
+                continue;
+            }
+
+            $mapper = ag($map, 'map', null);
+
+            if (false === is_array($mapper)) {
+                $this->logger->warning("Ignoring '{type}.{key}'. map value must be an object. '{given}' is given.", [
+                    'key' => $key,
+                    'type' => $this->type,
+                    'given' => get_debug_type($mapper),
+                ]);
+                continue;
+            }
+
+            $from = ag($mapper, 'from', null);
+            $to = ag($mapper, 'to', null);
+
+            if (empty($from) || false === is_string($from)) {
+                $this->logger->warning("Ignoring '{type}.{key}'. map.from field is empty or not a string.", [
+                    'type' => $this->type,
+                    'key' => $key,
+                ]);
+                continue;
+            }
+
+            if (empty($to) || false === is_string($to)) {
+                $this->logger->warning("Ignoring '{type}.{key}'. map.to field is empty or not a string.", [
+                    'type' => $this->type,
+                    'key' => $key,
+                ]);
+                continue;
+            }
+
+            if (false === Guid::validateGUIDName($to)) {
+                $this->logger->warning("Ignoring '{type}.{key}'. map.to '{to}' field does not starts with 'guid_'.", [
+                    'type' => $this->type,
+                    'key' => $key,
+                    'to' => $to,
+                ]);
+                continue;
+            }
+
+            if (false === in_array($to, $supported)) {
+                $this->logger->warning("Ignoring '{type}.{key}'. map.to field is not a supported GUID type.", [
+                    'type' => $this->type,
+                    'key' => $key,
+                    'to' => $to,
+                ]);
+                continue;
+            }
+
+            $this->guidMapper[$from] = $to;
+        }
     }
 
     public function withContext(Context $context): self
@@ -79,16 +229,18 @@ protected function ListExternalIds(array $guids, array $context = [], bool $log
         $type = JellyfinClient::TYPE_MAPPER[$type] ?? $type;
 
         foreach (array_change_key_case($guids, CASE_LOWER) as $key => $value) {
-            if (null === (self::GUID_MAPPER[$key] ?? null) || empty($value)) {
+            if (null === ($this->guidMapper[$key] ?? null) || empty($value)) {
                 continue;
             }
 
             try {
                 if (true === isIgnoredId($this->context->backendName, $type, $key, $value, $id)) {
                     if (true === $log) {
                         $this->logger->debug(
-                            'Ignoring [{backend}] external id [{source}] for {item.type} [{item.title}] as requested.',
+                            "{class}: Ignoring '{client}: {backend}' external id '{source}' for {item.type} '{item.id}: {item.title}' as requested.",
                             [
+                                'class' => afterLast(static::class, '\\'),
+                                'client' => $this->context->clientName,
                                 'backend' => $this->context->backendName,
                                 'source' => $key . '://' . $value,
                                 'guid' => [
@@ -102,12 +254,13 @@ protected function ListExternalIds(array $guids, array $context = [], bool $log
                     continue;
                 }
 
-                $guid[self::GUID_MAPPER[$key]] = $value;
+                $guid[$this->guidMapper[$key]] = $value;
             } catch (Throwable $e) {
                 if (true === $log) {
                     $this->logger->error(
-                        message: 'Exception [{error.kind}] was thrown unhandled during [{client}: {backend}] parsing [{agent}] identifier. Error [{error.message} @ {error.file}:{error.line}].',
+                        message: "{class}: Exception '{error.kind}' was thrown unhandled during '{client}: {backend}' parsing '{agent}' identifier. Error '{error.message}' at '{error.file}:{error.line}'.",
                         context: [
+                            'class' => afterLast(static::class, '\\'),
                             'backend' => $this->context->backendName,
                             'client' => $this->context->clientName,
                             'error' => [
@@ -136,4 +289,16 @@ protected function ListExternalIds(array $guids, array $context = [], bool $log
 
         return $guid;
     }
+
+    /**
+     * Get the configuration.
+     *
+     * @return array
+     */
+    public function getConfig(): array
+    {
+        return [
+            'guidMapper' => $this->guidMapper,
+        ];
+    }
 }