- add OpenApi documentation

- Improve api error handling
- add attach/detach/sync logic and policies  for relationships
- add actions for rediscovery, muting and maintenance
- reallign relationships to follow naming convention

Author: Yoyasp

app/Exceptions/ErrorReporting.php

@@ -27,13 +27,24 @@
 namespace App\Exceptions;
 
 use App\Facades\LibrenmsConfig;
+use App\Http\Middleware\EnforceJsonApi;
+use Binaryk\LaravelRestify\Exceptions\RepositoryNotFoundException;
+use Illuminate\Auth\Access\AuthorizationException;
+use Illuminate\Auth\AuthenticationException;
 use Illuminate\Cache\RateLimiting\Limit;
+use Illuminate\Database\Eloquent\ModelNotFoundException;
 use Illuminate\Foundation\Configuration\Exceptions;
+use Illuminate\Http\Exceptions\ThrottleRequestsException;
+use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Http\Response;
 use Illuminate\Support\Str;
+use Illuminate\Validation\ValidationException;
 use LibreNMS\Util\Git;
 use Spatie\LaravelIgnition\Facades\Flare;
+use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
+use Symfony\Component\HttpKernel\Exception\MethodNotAllowedHttpException;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
 use Throwable;
 
 class ErrorReporting
@@ -79,7 +90,7 @@ public function report(Throwable $e): bool
         return true;
     }
 
-    public function render(Throwable $exception, Request $request): ?Response
+    public function render(Throwable $exception, Request $request): Response|JsonResponse|null
     {
         // try to upgrade generic exceptions to more specific ones
         if (! config('app.debug')) {
@@ -94,9 +105,136 @@ public function render(Throwable $exception, Request $request): ?Response
             }
         }
 
+        if ($request->is('api/v1/*') || $request->is('api/v1')) {
+            return self::renderApiException($exception);
+        }
+
         return null; // use default rendering
     }
 
+    /**
+     * Render any exception as a JSON:API errors-array document for v1 API requests.
+     * Public + static so it can be unit-tested without a full HTTP cycle.
+     */
+    public static function renderApiException(Throwable $e): JsonResponse
+    {
+        [$status, $code, $title] = self::classifyException($e);
+
+        if ($e instanceof ValidationException) {
+            $entries = [];
+            foreach ($e->errors() as $field => $messages) {
+                foreach ((array) $messages as $message) {
+                    $entries[] = [
+                        'status' => (string) $status,
+                        'code' => $code,
+                        'title' => $title,
+                        'detail' => $message,
+                        'source' => ['pointer' => '/' . ltrim((string) $field, '/')],
+                    ];
+                }
+            }
+            if ($entries === []) {
+                $entries[] = self::buildSingleErrorEntry($e, $status, $code, $title);
+            }
+        } else {
+            $entries = [self::buildSingleErrorEntry($e, $status, $code, $title)];
+        }
+
+        if ($status >= 500 && config('app.debug')) {
+            $entries[0]['meta'] = [
+                'exception' => $e::class,
+                'file' => $e->getFile(),
+                'line' => $e->getLine(),
+                'trace' => self::formatTrace($e),
+            ];
+        }
+
+        return response()->json(
+            ['errors' => $entries],
+            $status,
+            ['Content-Type' => EnforceJsonApi::CONTENT_TYPE],
+        );
+    }
+
+    /**
+     * @return array{0:int,1:string,2:string} [status, code, title]
+     */
+    private static function classifyException(Throwable $e): array
+    {
+        if ($e instanceof ValidationException) {
+            return [$e->status, 'validation_failed', 'Validation Failed'];
+        }
+        if ($e instanceof AuthenticationException) {
+            return [401, 'unauthenticated', 'Unauthenticated'];
+        }
+        if ($e instanceof AuthorizationException) {
+            return [403, 'forbidden', 'Forbidden'];
+        }
+        if ($e instanceof ModelNotFoundException || $e instanceof RepositoryNotFoundException) {
+            return [404, 'not_found', 'Not Found'];
+        }
+        if ($e instanceof ThrottleRequestsException) {
+            return [429, 'too_many_requests', 'Too Many Requests'];
+        }
+        if ($e instanceof HttpExceptionInterface) {
+            return self::classifyByStatus($e->getStatusCode());
+        }
+
+        return [500, 'server_error', 'Server Error'];
+    }
+
+    /**
+     * @return array{0:int,1:string,2:string}
+     */
+    private static function classifyByStatus(int $status): array
+    {
+        return match ($status) {
+            401 => [401, 'unauthenticated', 'Unauthenticated'],
+            403 => [403, 'forbidden', 'Forbidden'],
+            404 => [404, 'not_found', 'Not Found'],
+            405 => [405, 'method_not_allowed', 'Method Not Allowed'],
+            429 => [429, 'too_many_requests', 'Too Many Requests'],
+            default => [
+                $status,
+                'http_' . $status,
+                Response::$statusTexts[$status] ?? 'Error',
+            ],
+        };
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    private static function buildSingleErrorEntry(Throwable $e, int $status, string $code, string $title): array
+    {
+        $detail = $e->getMessage();
+        if ($detail === '' || ($status >= 500 && ! config('app.debug'))) {
+            $detail = $status >= 500 ? 'An unexpected error occurred.' : $title;
+        }
+
+        return [
+            'status' => (string) $status,
+            'code' => $code,
+            'title' => $title,
+            'detail' => $detail,
+        ];
+    }
+
+    /**
+     * @return string[]
+     */
+    private static function formatTrace(Throwable $e): array
+    {
+        $frames = [];
+        foreach (array_slice($e->getTrace(), 0, 10) as $frame) {
+            $location = ($frame['file'] ?? '?') . ':' . ($frame['line'] ?? '?');
+            $call = ($frame['class'] ?? '') . ($frame['type'] ?? '') . ($frame['function'] ?? '');
+            $frames[] = trim($location . ' ' . $call);
+        }
+
+        return $frames;
+    }
+
     /**
      * Checks the state of the config and current install to determine if reporting should be enabled
      * The primary factor is the setting reporting.error

app/Http/Middleware/EnforceJsonApi.php

@@ -15,7 +15,12 @@ public function handle(Request $request, Closure $next): Response
         // Reject request bodies with wrong Content-Type (JSON:API §5.3)
         if ($request->getContent() && ! $this->isJsonApi($request->header('Content-Type', ''))) {
             return response()->json([
-                'errors' => [['status' => '415', 'title' => 'Unsupported Media Type']],
+                'errors' => [[
+                    'status' => '415',
+                    'code' => 'unsupported_media_type',
+                    'title' => 'Unsupported Media Type',
+                    'detail' => 'Request body must be application/vnd.api+json or application/json.',
+                ]],
             ], 415)->withHeaders(['Content-Type' => self::CONTENT_TYPE]);
         }
 

app/Http/Middleware/RestifyAttachRelationResolver.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use Binaryk\LaravelRestify\Fields\EagerField;
+use Binaryk\LaravelRestify\Restify;
+use Closure;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * Lets repositories advertise URL-friendly attach/sync/detach segments that
+ * don't match the underlying Eloquent relation method name.
+ *
+ * For URLs like /api/v1/{parent}/{id}/(attach|sync|detach)/{segment}, we look
+ * up the field on the parent repository whose `attribute` equals `{segment}`
+ * and, when its `relation` property differs (e.g. attribute='device-groups',
+ * relation='groups'), inject `viaRelationship` on the request so Restify's
+ * controllers call `$model->groups()` rather than the literal URL segment.
+ *
+ * Effectively decouples the URL slug from the model method, which PHP requires
+ * to be a valid identifier (no hyphens).
+ */
+class RestifyAttachRelationResolver
+{
+    public function handle(Request $request, Closure $next): Response
+    {
+        if (! preg_match('#^api/v1/([^/]+)/[^/]+/(?:attach|sync|detach)/([^/?]+)#', $request->path(), $m)) {
+            return $next($request);
+        }
+
+        [$_, $parentSegment, $relatedSegment] = $m;
+
+        $repoClass = Restify::repositoryClassForKey($parentSegment);
+        if (! $repoClass || ! method_exists($repoClass, 'related')) {
+            return $next($request);
+        }
+
+        foreach ($repoClass::related() as $field) {
+            if (! $field instanceof EagerField || $field->attribute !== $relatedSegment) {
+                continue;
+            }
+
+            if (isset($field->relation) && $field->relation !== $field->attribute) {
+                // Laravel Request's __get checks input first then route params;
+                // merging the value into the input bag is the simplest way to
+                // make vendor's `$request->viaRelationship` resolve to the
+                // model method name we want (e.g. groups()).
+                $request->merge(['viaRelationship' => $field->relation]);
+            }
+            break;
+        }
+
+        return $next($request);
+    }
+}

app/Http/Requests/Restify/AttachRequest.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Http\Requests\Restify;
+
+use Binaryk\LaravelRestify\Http\Requests\RepositoryAttachRequest;
+use Illuminate\Support\Collection;
+
+class AttachRequest extends RepositoryAttachRequest
+{
+    use ResolvesRelatedRepositoryFromField;
+
+    public function attachRelatedModels(): Collection
+    {
+        return $this->resolveRelatedModels();
+    }
+}

app/Http/Requests/Restify/DetachRequest.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Http\Requests\Restify;
+
+use Binaryk\LaravelRestify\Http\Requests\RepositoryDetachRequest;
+use Illuminate\Support\Collection;
+
+class DetachRequest extends RepositoryDetachRequest
+{
+    use ResolvesRelatedRepositoryFromField;
+
+    public function detachRelatedModels(): Collection
+    {
+        return $this->resolveRelatedModels();
+    }
+}

app/Http/Requests/Restify/ResolvesRelatedRepositoryFromField.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace App\Http\Requests\Restify;
+
+use Binaryk\LaravelRestify\Fields\BelongsToMany;
+use Binaryk\LaravelRestify\Fields\EagerField;
+use Binaryk\LaravelRestify\Repositories\Repository;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Collection;
+
+/**
+ * Replaces Restify's default `Restify::repositoryForTable($urlSegment)` lookup
+ * (which fails whenever the URL segment doesn't equal the related model's
+ * actual database table name  e.g. `attach/device-groups` against the
+ * `device_groups` table) with a field-driven lookup that uses the parent
+ * repository's `related()` declaration.
+ *
+ * The URL segment is matched to the field's `attribute`. The target repository
+ * is taken from the field's `repositoryClass`. This works for every attach/
+ * sync/detach URL regardless of how it differs from the underlying table.
+ */
+trait ResolvesRelatedRepositoryFromField
+{
+    protected function resolveRelatedModels(): Collection
+    {
+        $segment = $this->relatedRepository;
+
+        $field = collect($this->repository()::related())
+            ->first(fn ($candidate) => $candidate instanceof EagerField && $candidate->attribute === $segment);
+
+        if (! $field instanceof BelongsToMany) {
+            abort(400, "Missing BelongsToMany relation for [{$segment}] on the parent repository.");
+        }
+
+        /** @var class-string<Repository> $relatedClass */
+        $relatedClass = $field->repositoryClass;
+        /** @var Model $model */
+        $model = app($relatedClass::guessModelClassName());
+
+        return collect(Arr::wrap($this->input($segment)))
+            ->map(fn ($id) => $model->newModelQuery()->whereKey($id)->first());
+    }
+}

app/Http/Requests/Restify/SyncRequest.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Http\Requests\Restify;
+
+use Binaryk\LaravelRestify\Http\Requests\RepositorySyncRequest;
+use Illuminate\Support\Collection;
+
+class SyncRequest extends RepositorySyncRequest
+{
+    use ResolvesRelatedRepositoryFromField;
+
+    public function syncRelatedModels(): Collection
+    {
+        return $this->resolveRelatedModels();
+    }
+}

app/Models/AlertRule.php

@@ -189,6 +189,14 @@ public function alertOperation(): BelongsTo
         return $this->belongsTo(AlertOperation::class, 'alert_operation_id');
     }
 
+    /**
+     * @return BelongsToMany<AlertTemplate, $this>
+     */
+    public function templates(): BelongsToMany
+    {
+        return $this->belongsToMany(AlertTemplate::class, 'alert_template_map', 'alert_rule_id', 'alert_templates_id');
+    }
+
     /**
      * Backwards-compatible shape: one array entry per segment (same as legacy multi-row operations).
      *