create-nevela 0.7.0 → 0.8.0

package/template/laravel/src/Http/ActionController.php

@@ -0,0 +1,222 @@
+<?php
+
+namespace Nevela\Laravel\Http;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Gate;
+use Illuminate\Support\Facades\Validator;
+use Illuminate\Validation\ValidationException;
+use Nevela\Laravel\Nevela;
+use Nevela\Laravel\Support\Action;
+use Nevela\Laravel\Support\Descriptor;
+use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
+use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+use Throwable;
+
+/**
+ * A resource's own actions: what its descriptor's "actions" section names.
+ *
+ *   POST {slug}/{id}/_actions/{action}   { input }         on one record
+ *   POST {slug}/_actions/{action}        { input }         on the resource as a whole
+ *   POST {slug}/_actions/{action}        { ids, input }    a record action, on a selection
+ *
+ * One controller for every resource, like the trash: every action is reached the same
+ * way and differs only in the class that does it, App\Nevela\Actions\<Resource>\<Action>.
+ * Here is everything around that class: who may, whether it applies, whether what was
+ * asked for is valid, and what the person is told when it fails.
+ */
+final class ActionController
+{
+    /** The most records a selection can be: what the dashboard's table can select at once, with room. */
+    private const MOST = 500;
+
+    public function record(Request $request, string $slug, string $id, string $action): JsonResponse
+    {
+        [$descriptor, $definition] = $this->find($slug, $action, 'record');
+        $this->authorize($request, $descriptor, $definition);
+        $record = $this->one($descriptor, $id) ?? throw new NotFoundHttpException;
+        if (! $this->applies($descriptor, $definition, $record)) {
+            return response()->json(['error' => "{$definition->label} can't be done to this ".strtolower($descriptor->label).' as it is now.', 'code' => 'NOT_APPLICABLE'], 409);
+        }
+        $input = $this->input($request, $definition);
+
+        return $this->run($definition, function () use ($descriptor, $definition, $record, $input, $request) {
+            $message = $this->handler($descriptor, $definition)->handle($record, $input);
+
+            return ['message' => is_string($message) && $message !== '' ? $message : "{$definition->label}: done.", 'record' => $this->present($descriptor, $record, $request)];
+        });
+    }
+
+    public function collection(Request $request, string $slug, string $action): JsonResponse
+    {
+        [$descriptor, $definition] = $this->find($slug, $action, null);
+        $this->authorize($request, $descriptor, $definition);
+        $input = $this->input($request, $definition);
+
+        if ($definition->on === 'collection') {
+            return $this->run($definition, function () use ($descriptor, $definition, $input) {
+                $message = $this->handler($descriptor, $definition)->handle($input);
+
+                return ['message' => is_string($message) && $message !== '' ? $message : "{$definition->label}: done."];
+            });
+        }
+
+        // A record action, on several records at once.
+        if (! $definition->many) {
+            throw new NotFoundHttpException;
+        }
+        $ids = $request->input('ids');
+        if (! is_array($ids) || ! array_is_list($ids) || $ids === [] || count($ids) > self::MOST) {
+            return response()->json(['error' => 'Send the records as "ids": a list of 1 to '.self::MOST.'.'], 422);
+        }
+
+        return $this->run($definition, function () use ($descriptor, $definition, $input, $ids) {
+            $handler = $this->handler($descriptor, $definition);
+            $done = 0;
+            $skipped = 0;
+            foreach (array_unique(array_map('strval', array_filter($ids, 'is_scalar'))) as $id) {
+                $record = $this->one($descriptor, $id);
+                // One it no longer applies to, or that has gone, is passed over: the rest still want doing.
+                if ($record === null || ! $this->applies($descriptor, $definition, $record)) {
+                    $skipped++;
+
+                    continue;
+                }
+                $handler->handle($record, $input);
+                $done++;
+            }
+            $what = strtolower($done === 1 ? $descriptor->label : $descriptor->pluralLabel);
+
+            return [
+                'message' => "{$definition->label}: {$done} {$what}".($skipped > 0 ? ", and {$skipped} left as ".($skipped === 1 ? 'it was' : 'they were').'.' : '.'),
+                'done' => $done,
+                'skipped' => $skipped,
+            ];
+        });
+    }
+
+    /**
+     * The resource and the action an address names.
+     *
+     * @param  'record'|null  $on  Where it must be, or either
+     * @return array{Descriptor, Action}
+     */
+    private function find(string $slug, string $action, ?string $on): array
+    {
+        foreach (Nevela::all() as $descriptor) {
+            $definition = $descriptor->slug === $slug ? ($descriptor->actions[$action] ?? null) : null;
+            if ($definition !== null && ($on === null || $definition->on === $on)) {
+                return [$descriptor, $definition];
+            }
+        }
+        throw new NotFoundHttpException;
+    }
+
+    /** Its own permission, by name. Being able to edit the records is not being able to do this to them. */
+    private function authorize(Request $request, Descriptor $descriptor, Action $action): void
+    {
+        if (! $request->user()?->can("{$descriptor->table}.{$action->key()}")) {
+            throw new AccessDeniedHttpException("You don't have access to this.");
+        }
+    }
+
+    /** The record with this id, if there is one and the person may see it. */
+    private function one(Descriptor $descriptor, string $id): ?Model
+    {
+        $model = "App\\Models\\{$descriptor->name}";
+        if (! class_exists($model) || ($descriptor->idType === 'int' && ! preg_match('/^[0-9]{1,18}$/', $id))) {
+            return null;
+        }
+        $record = $model::query()->find($id);
+
+        return $record !== null && Gate::allows('view', $record) ? $record : null;
+    }
+
+    private function applies(Descriptor $descriptor, Action $action, Model $record): bool
+    {
+        $values = [];
+        foreach (array_keys($action->when) as $field) {
+            $values[$field] = $record->getAttribute($descriptor->fields[$field]->column());
+        }
+
+        return $action->applies($values);
+    }
+
+    /**
+     * What the action asked for, checked. A problem is reported against its field, the way
+     * a form's is, so the sheet can show it there.
+     *
+     * @return array<string, mixed>
+     */
+    private function input(Request $request, Action $action): array
+    {
+        $sent = $request->input('input', []);
+        $sent = is_array($sent) ? $sent : [];
+        $validator = Validator::make($sent, $action->rules());
+        $validator->after(function ($validator) use ($sent, $action) {
+            foreach (array_keys($sent) as $key) {
+                if (! isset($action->fields[$key])) {
+                    $validator->errors()->add((string) $key, 'Unknown field.');
+                }
+            }
+        });
+        if ($validator->fails()) {
+            throw new ValidationException($validator);
+        }
+
+        return $validator->validated();
+    }
+
+    private function handler(Descriptor $descriptor, Action $action): object
+    {
+        $class = "App\\Nevela\\Actions\\{$descriptor->name}\\{$action->className()}";
+        if (! class_exists($class) || ! method_exists($class, 'handle')) {
+            throw new \LogicException("{$action->label} has no class to do it. Run: php artisan nevela:generate {$descriptor->name}");
+        }
+
+        return app($class);
+    }
+
+    /**
+     * Do it, all of it or none: what the class changed in the database is undone when it
+     * throws, and the person is told that it didn't work and that nothing was changed.
+     *
+     * @param  callable(): array<string, mixed>  $do
+     */
+    private function run(Action $action, callable $do): JsonResponse
+    {
+        try {
+            return response()->json(DB::transaction($do));
+        } catch (HttpExceptionInterface|ValidationException $e) {
+            throw $e; // the class said why itself: abort(409, …), or a validation error
+        } catch (Throwable $e) {
+            report($e);
+
+            return response()->json(array_filter([
+                'error' => "{$action->label} didn't work, and nothing was changed.",
+                // Said to whoever is building the app, not to whoever is using it.
+                'detail' => config('app.debug') ? $e->getMessage() : null,
+            ]), 500);
+        }
+    }
+
+    /**
+     * The record as the API shows it, after the action: what the page it was pressed on now needs.
+     *
+     * @return array<string, mixed>|null
+     */
+    private function present(Descriptor $descriptor, Model $record, Request $request): ?array
+    {
+        $resource = "App\\Http\\Resources\\Nevela\\{$descriptor->name}Resource";
+        if (! $record->exists || ! class_exists($resource)) {
+            return null;
+        }
+        $fresh = $record->fresh();
+
+        return $fresh === null ? null : (new $resource($fresh))->resolve($request);
+    }
+}

package/template/laravel/src/Http/PublicController.php

@@ -0,0 +1,210 @@
+<?php
+
+namespace Nevela\Laravel\Http;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use Illuminate\Support\Facades\DB;
+use Nevela\Laravel\Media\Uploads;
+use Nevela\Laravel\Models\Upload;
+use Nevela\Laravel\Nevela;
+use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Support\PublicAccess;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
+/**
+ * What anyone can call, signed in or not: a resource's "public" section.
+ *
+ *   GET  {prefix}/public/{slug}          the list, of the records the model says are public
+ *   GET  {prefix}/public/{slug}/{id}     one of them, by id or by the field the section names
+ *   POST {prefix}/public/{slug}          create one, from the fields the section lists
+ *   PUT  {prefix}/public/_nevela/uploads/{Resource}/{field}   a file for such a create
+ *
+ * The routes are generated (routes/nevela-public.php), one set per resource that has a
+ * section and only for what it opens, so a resource without one has nothing here to call.
+ *
+ * Nobody is asked who they are, so nothing here trusts what it is sent beyond what the
+ * section allows: fields that aren't listed are never sent out and never taken in, and
+ * the rules are the generated request's own.
+ */
+final class PublicController
+{
+    /** How long a file uploaded for a create waits for that create, in seconds. */
+    public const CLAIM_SECONDS = 3600;
+
+    public function index(Request $request): JsonResponse
+    {
+        [$descriptor, $public] = $this->open($request, 'read');
+        $resourceClass = $this->resourceClass($descriptor);
+
+        // Sorting, filtering and search are the signed-in list's, over the listed fields only.
+        $response = Nevela::listFor($this->readable($descriptor), $descriptor->only($public->read), $request, $resourceClass);
+        if ($response->getStatusCode() !== 200) {
+            return $response;
+        }
+        $body = $response->getData(true);
+        $body['data'] = array_map(fn (array $row) => $this->visible($descriptor, $public, $row), $body['data']);
+
+        return response()->json($body);
+    }
+
+    public function show(Request $request): JsonResponse
+    {
+        [$descriptor, $public] = $this->open($request, 'read');
+        $id = (string) $request->route('id');
+        $query = $this->readable($descriptor);
+        if ($public->by !== null) {
+            $query->where($descriptor->fields[$public->by]->column(), $id);
+        } elseif ($descriptor->idType === 'int' ? ! preg_match('/^[0-9]{1,18}$/', $id) : ! \Illuminate\Support\Str::isUuid($id)) {
+            throw new NotFoundHttpException;
+        } else {
+            $query->whereKey($id);
+        }
+        $record = $query->first() ?? throw new NotFoundHttpException;
+        $resourceClass = $this->resourceClass($descriptor);
+
+        return response()->json($this->visible($descriptor, $public, (new $resourceClass($record))->resolve($request)));
+    }
+
+    public function store(Request $request): JsonResponse|Response
+    {
+        [$descriptor, $public] = $this->open($request, 'create');
+        $requestClass = "App\\Http\\Requests\\Nevela\\{$descriptor->name}Request";
+        $model = $this->model($descriptor);
+        $input = $request->json()->all() ?: $request->request->all();
+
+        $checked = (new $requestClass)->forFields($public->create, is_array($input) ? $input : []);
+        // A file has to be one a visitor uploaded for this, a moment ago, and not yet used.
+        foreach ($public->create as $field) {
+            $key = $checked['values'][$descriptor->fields[$field]->column()] ?? null;
+            if ($descriptor->fields[$field]->kind === 'file' && is_string($key) && $key !== '' && ! $this->claimable($descriptor, $field, $key)) {
+                $checked['issues'][] = ['path' => $field, 'message' => 'Upload the file again: this one has been used, or was uploaded too long ago.'];
+            }
+        }
+        if ($checked['issues'] !== []) {
+            return response()->json(['error' => 'Validation failed.', 'issues' => $checked['issues']], 422);
+        }
+
+        $record = DB::transaction(function () use ($model, $checked, $descriptor, $public) {
+            $record = $model::create($checked['values']);
+            // Claimed: the nightly clear-out of uploads nobody used leaves it alone from here on.
+            foreach ($public->create as $field) {
+                $key = $descriptor->fields[$field]->kind === 'file' ? $record->getAttribute($descriptor->fields[$field]->column()) : null;
+                if (is_string($key) && $key !== '') {
+                    Upload::query()->where('key', $key)->update(['uploaded_by' => Uploads::CLAIMED]);
+                }
+            }
+
+            return $record;
+        });
+
+        // What they may read of what they made, or nothing where nothing may be read.
+        if ($public->read === null) {
+            return response()->noContent(201);
+        }
+        $resourceClass = $this->resourceClass($descriptor);
+
+        return response()->json($this->visible($descriptor, $public, (new $resourceClass($record->refresh()))->resolve($request)), 201);
+    }
+
+    /** A file for a public create: the field's own types and size limit, and no sign-in. */
+    public function upload(Request $request): JsonResponse
+    {
+        [$descriptor, $public] = $this->open($request, 'create');
+        $field = (string) $request->route('field');
+        $definition = $descriptor->fields[$field] ?? null;
+        if ($definition === null || $definition->kind !== 'file' || ! in_array($field, $public->create, true)) {
+            throw new NotFoundHttpException;
+        }
+        $upload = UploadController::receive($request, $descriptor, $definition);
+        if ($upload instanceof JsonResponse) {
+            return $upload;
+        }
+        // Marked as a visitor's, waiting to be used: see claimable() and Uploads::purgeUnclaimed().
+        $upload->update(['uploaded_by' => Uploads::UNCLAIMED]);
+
+        return response()->json(Uploads::ref($upload->key), 201);
+    }
+
+    /**
+     * The resource a route is for, if this part of it is open. The route is only there when
+     * it is, so this failing means a route file older than the descriptor.
+     *
+     * Which resource is a default set on the route. Laravel hands route parameters to a
+     * controller in order and not by name, with defaults after what the address holds, so
+     * it is asked for by its name here.
+     *
+     * @return array{Descriptor, PublicAccess}
+     */
+    private function open(Request $request, string $what): array
+    {
+        try {
+            $descriptor = Nevela::resource((string) $request->route('resource'));
+        } catch (\InvalidArgumentException) {
+            throw new NotFoundHttpException;
+        }
+        if ($descriptor->public?->{$what} === null || ! class_exists($this->model($descriptor))) {
+            throw new NotFoundHttpException;
+        }
+
+        return [$descriptor, $descriptor->public];
+    }
+
+    /** @return class-string<Model> */
+    private function model(Descriptor $descriptor): string
+    {
+        return "App\\Models\\{$descriptor->name}";
+    }
+
+    /** @return class-string<\Illuminate\Http\Resources\Json\JsonResource> */
+    private function resourceClass(Descriptor $descriptor): string
+    {
+        return "App\\Http\\Resources\\Nevela\\{$descriptor->name}Resource";
+    }
+
+    /**
+     * The records anyone may read: what the model's publicQuery scope lets through. A model
+     * without the scope has said nothing, and nothing is what is public.
+     */
+    private function readable(Descriptor $descriptor): Builder
+    {
+        $model = $this->model($descriptor);
+        $query = $model::query();
+
+        return method_exists($model, 'scopePublicQuery') ? $query->publicQuery() : $query->whereRaw('1 = 0');
+    }
+
+    /**
+     * A record as anyone may see it: its id and the listed fields, and for a file the
+     * details that go with its key. Nothing else, whatever the API resource holds.
+     *
+     * @param  array<string, mixed>  $row
+     * @return array<string, mixed>
+     */
+    private function visible(Descriptor $descriptor, PublicAccess $public, array $row): array
+    {
+        $seen = ['id' => $row['id'] ?? null];
+        foreach ($public->read ?? [] as $field) {
+            $seen[$field] = $row[$field] ?? null;
+            if ($descriptor->fields[$field]->kind === 'file') {
+                $seen[$field.'File'] = $row[$field.'File'] ?? null;
+            }
+        }
+
+        return $seen;
+    }
+
+    /** Whether a key is a file a visitor uploaded to this field within the hour, that no record has yet. */
+    private function claimable(Descriptor $descriptor, string $field, string $key): bool
+    {
+        $upload = Upload::query()->where('key', $key)->where('resource', $descriptor->name)->where('field', $field)->first();
+
+        return $upload !== null
+            && $upload->getAttribute('uploaded_by') === Uploads::UNCLAIMED
+            && $upload->created_at !== null && $upload->created_at->gt(now()->subSeconds(self::CLAIM_SECONDS))
+            && ! DB::table($descriptor->table)->where($descriptor->fields[$field]->column(), $key)->exists();
+    }
+}

package/template/laravel/src/Http/PublicThrottle.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace Nevela\Laravel\Http;
+
+use Closure;
+use Illuminate\Routing\Middleware\ThrottleRequests;
+use Nevela\Laravel\Auth\Account;
+
+/**
+ * The throttle on a resource's public routes: Laravel's own, counting the right thing.
+ *
+ * A public page or form is usually reached through the web app, whose server makes the
+ * call. Counted as they arrive, every visitor would be that one server: ten enquiries a
+ * minute for the whole world, and a busy page would lock itself out. So, for a request
+ * that proves it comes from the web app (the secret the two share, as for the list of
+ * signed-in devices):
+ *
+ * - one made for a visitor is counted against that visitor's address, which the web app
+ *   passes on as X-Nevela-Client. It is the address the proxy in front of the web app saw,
+ *   not the one the request claimed for itself: a visitor who could choose it could have
+ *   a fresh allowance with every request. Where the web app can't tell (it says
+ *   "unknown"), visitors are counted together, from the web app's own address;
+ * - one made for nobody in particular, such as a page being built to be cached and
+ *   shown to many, is the site reading its own data and is not counted. Such a request
+ *   carries the secret and names no visitor at all.
+ *
+ * Anything else is counted against the address it came from, as ever.
+ */
+final class PublicThrottle extends ThrottleRequests
+{
+    public function handle($request, Closure $next, $maxAttempts = 60, $decayMinutes = 1, $prefix = '')
+    {
+        if (Account::fromDashboard($request)) {
+            $visitor = $request->header('X-Nevela-Client');
+            if ($visitor === null) {
+                // Only on the strength of the secret: "from this machine, in development" is
+                // enough to believe an address, and not enough to stop counting.
+                if ((string) config('nevela.auth.proxy_secret', '') !== '') {
+                    return $next($request);
+                }
+            } elseif (filter_var($visitor, FILTER_VALIDATE_IP)) {
+                $request->server->set('REMOTE_ADDR', $visitor);
+            }
+        }
+
+        return parent::handle($request, $next, $maxAttempts, $decayMinutes, $prefix);
+    }
+}