Added Endpoint Discovery

Author: mgerzabek

config.php

@@ -103,4 +103,9 @@
      * Configuration for OpenAPI schema generation
      */
     'openapi' => [],
+
+    /**
+     * Configuration for multiple service endpoints
+     */
+    'endpoints' => [],
 ];

doc/.vuepress/config.js

@@ -134,6 +134,7 @@ module.exports = {
                 children: [
                     'getting-started/',
                     'getting-started/configuration',
+                    'getting-started/endpoint',
                     'getting-started/facade',
                     'getting-started/routing',
                     'getting-started/authentication',

doc/getting-started/endpoint.md

@@ -0,0 +1,43 @@
+# Service Endpoints
+
+At this point we assume you already published the `lodata.php` config file to your project.
+
+In case you want to distribute different service endpoints with your Laravel app, you can do so by providing one or more service endpoints to the package. This especially comes in handy when following a modularized setup.
+
+Each of your modules could register its own service endpoint with an `\Flat3\Lodata\Endpoint` like this:
+
+```php
+/**
+ * At the end of `config/lodata.php` 
+ */
+'endpoints' => [
+    'projects' ⇒ \App\Projects\ProjectEndpoint::class,
+],
+```
+
+With that configuration a separate `$metadata` service file will be available via `https://<server>:<port>/<lodata.prefix>/projects/$metadata`.
+
+If the `endpoints` array stays empty (the default), only one global service endpoint is created.
+
+## Selective Discovery
+
+With endpoints, you can now discover all your entities and annotations in a separate class via the `discover` function. 
+
+```php
+use App\Model\Contact;
+use Flat3\Lodata\Model;
+
+/**
+ * Discovers Schema and Annotations of the `$metadata` file for
+ * the service.
+ */
+public function discover(Model $model): Model
+{
+    // register all of your $metadata capabilities
+    $model->discover(Contact::class); 
+    …
+    return $model;
+}
+```
+
+Furthermore, the `discover` function will only be executed when serving actual oData routes. This will enhance page speed for routes outside the `config('lodata.prefix')` URI space. 

doc/package.json

@@ -5,9 +5,9 @@
     },
     "devDependencies": {
         "@kawarimidoll/vuepress-plugin-tailwind": "^2.0.0",
-        "@vuepress/plugin-back-to-top": "^1.9.5",
-        "@vuepress/plugin-nprogress": "^1.9.5",
-        "vuepress": "^1.9.5",
+        "@vuepress/plugin-back-to-top": "^1.9.10",
+        "@vuepress/plugin-nprogress": "^1.9.10",
+        "vuepress": "^1.9.10",
         "vuepress-plugin-container": "^2.1.5",
         "vuepress-plugin-sitemap": "^2.3.1"
     }

src/Controller/ODCFF.php

@@ -8,7 +8,8 @@
 use Flat3\Lodata\Exception\Protocol\NotFoundException;
 use Flat3\Lodata\Facades\Lodata;
 use Flat3\Lodata\Helper\Constants;
-use Flat3\Lodata\ServiceProvider;
+use Flat3\Lodata\Endpoint;
+use Illuminate\Contracts\Container\BindingResolutionException;
 use Illuminate\Http\Response;
 use Illuminate\Routing\Controller;
 use Illuminate\Support\Facades\App;
@@ -27,6 +28,7 @@ class ODCFF extends Controller
      * Generate an ODCFF response for the provided entity set identifier
      * @param  string  $identifier  Identifier
      * @return Response Client response
+     * @throws BindingResolutionException
      */
     public function get(string $identifier): Response
     {
@@ -165,7 +167,7 @@ public function get(string $identifier): Response
         $formula = $mashupDoc->createElement('Formula');
         $formulaContent = $mashupDoc->createCDATASection(sprintf(
             'let Source = OData.Feed("%1$s", null, [Implementation="2.0"]), %2$s_table = Source{[Name="%2$s",Signature="table"]}[Data] in %2$s_table',
-            ServiceProvider::endpoint(),
+            app()->make(Endpoint::class)->endpoint(),
             $resourceId,
         ));
         $formula->appendChild($formulaContent);

src/Controller/PBIDS.php

@@ -6,8 +6,9 @@
 
 use Flat3\Lodata\Helper\Constants;
 use Flat3\Lodata\Helper\JSON;
-use Flat3\Lodata\ServiceProvider;
+use Flat3\Lodata\Endpoint;
 use Flat3\Lodata\Transaction\MediaType;
+use Illuminate\Contracts\Container\BindingResolutionException;
 use Illuminate\Http\Response;
 use Illuminate\Routing\Controller;
 use Illuminate\Support\Facades\App;
@@ -23,6 +24,7 @@ class PBIDS extends Controller
     /**
      * Generate a PowerBI data source discovery file
      * @return Response Client response
+     * @throws BindingResolutionException
      */
     public function get(): Response
     {
@@ -42,7 +44,7 @@ public function get(): Response
                     'details' => [
                         'protocol' => 'odata',
                         'address' => [
-                            'url' => ServiceProvider::endpoint(),
+                            'url' => app()->make(Endpoint::class)->endpoint(),
                         ],
                     ],
                 ],

src/Controller/Transaction.php

@@ -30,9 +30,9 @@
 use Flat3\Lodata\Interfaces\ResponseInterface;
 use Flat3\Lodata\Interfaces\TransactionInterface;
 use Flat3\Lodata\NavigationProperty;
+use Flat3\Lodata\Endpoint;
 use Flat3\Lodata\Operation;
 use Flat3\Lodata\PathSegment;
-use Flat3\Lodata\ServiceProvider;
 use Flat3\Lodata\Singleton;
 use Flat3\Lodata\Transaction\IEEE754Compatible;
 use Flat3\Lodata\Transaction\MediaType;
@@ -58,6 +58,7 @@
 use Flat3\Lodata\Transaction\ParameterList;
 use Flat3\Lodata\Transaction\Version;
 use Flat3\Lodata\Type\Collection;
+use Illuminate\Contracts\Container\BindingResolutionException;
 use Illuminate\Support\Arr;
 use Illuminate\Support\Facades\App;
 use Illuminate\Support\Str;
@@ -784,7 +785,7 @@ public function getPath(): string
      */
     public function getRequestPath(): string
     {
-        $route = ServiceProvider::route();
+        $route = app()->make(Endpoint::class)->route();
         return Str::substr($this->request->path(), strlen($route));
     }
 
@@ -947,20 +948,22 @@ private function getSystemQueryOptions(bool $prefixed = true): array
      * Get the service document context URL
      * https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_ServiceDocument
      * @return string Context URL
+     * @throws BindingResolutionException
      */
     public function getContextUrl(): string
     {
-        return ServiceProvider::endpoint().'$metadata';
+        return self::getResourceUrl().'$metadata';
     }
 
     /**
      * Get the service document resource URL
      * https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_ServiceDocument
      * @return string Resource URL
+     * @throws BindingResolutionException
      */
     public static function getResourceUrl(): string
     {
-        return ServiceProvider::endpoint();
+        return app()->make(Endpoint::class)->endpoint();
     }
 
     /**

src/Endpoint.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace Flat3\Lodata;
+
+class Endpoint
+{
+    /**
+     * @var string $serviceUri the &lt;service-uri> of the <code>Flat3\Lodata\Model</code>.
+     */
+    protected $serviceUri;
+
+    /**
+     * @var string $route the route prefix configured in <code>'lodata.prefix'</code>
+     */
+    protected $route;
+
+    /**
+     * @var string $endpoint the full url to the ODataService endpoint
+     */
+    protected $endpoint;
+
+    public function __construct(string $serviceUri)
+    {
+        $this->serviceUri = rtrim($serviceUri, '/');
+
+        $prefix = rtrim(config('lodata.prefix'), '/');
+        $this->route = ('' === $serviceUri)
+            ? $prefix
+            : $prefix . '/' . $this->serviceUri;
+
+        $this->endpoint = url($this->route) . '/';
+    }
+
+    /**
+     * @return string the path within the odata URI space, like in
+     * https://<server>:<port>/<config('lodata.prefix')>/<service-uri>/$metadata
+     */
+    public function endpoint(): string
+    {
+        return $this->endpoint;
+    }
+
+    public function route(): string
+    {
+        return $this->route;
+    }
+
+    /**
+     * Discovers Schema and Annotations of the `$metadata` file for
+     * the service.
+     */
+    public function discover(Model $model): Model
+    {
+        // override this function to register all of your $metadata capabilities
+        return $model;
+    }
+}

src/Entity.php

@@ -23,6 +23,7 @@
 use Flat3\Lodata\Interfaces\ResourceInterface;
 use Flat3\Lodata\Interfaces\ResponseInterface;
 use Flat3\Lodata\Transaction\MetadataContainer;
+use Illuminate\Contracts\Container\BindingResolutionException;
 use Illuminate\Http\Request;
 use Illuminate\Support\Str;
 
@@ -154,6 +155,9 @@ public function offsetSet($offset, $value): void
         }
     }
 
+    /**
+     * @throws BindingResolutionException
+     */
     public static function pipe(
         Transaction $transaction,
         string $currentSegment,
@@ -175,8 +179,9 @@ public static function pipe(
         }
 
         $entityId = $id->getValue();
-        if (Str::startsWith($entityId, ServiceProvider::endpoint())) {
-            $entityId = Str::substr($entityId, strlen(ServiceProvider::endpoint()));
+        $endpoint = app()->make(Endpoint::class)->endpoint();
+        if (Str::startsWith($entityId, $endpoint)) {
+            $entityId = Str::substr($entityId, strlen($endpoint));
         }
 
         return EntitySet::pipe($transaction, $entityId);

src/Model.php

@@ -17,6 +17,7 @@
 use Flat3\Lodata\Interfaces\ResourceInterface;
 use Flat3\Lodata\Interfaces\ServiceInterface;
 use Flat3\Lodata\Traits\HasAnnotations;
+use Illuminate\Contracts\Container\BindingResolutionException;
 
 /**
  * Model
@@ -339,10 +340,11 @@ public function discover($discoverable): self
     /**
      * Get the REST endpoint of this OData model
      * @return string REST endpoint
+     * @throws BindingResolutionException
      */
     public function getEndpoint(): string
     {
-        return ServiceProvider::endpoint();
+        return app()->make(Endpoint::class)->endpoint();
     }
 
     /**
@@ -351,7 +353,7 @@ public function getEndpoint(): string
      */
     public function getPbidsUrl(): string
     {
-        return ServiceProvider::endpoint().'_lodata/odata.pbids';
+        return $this->getEndpoint().'_lodata/odata.pbids';
     }
 
     /**
@@ -361,7 +363,7 @@ public function getPbidsUrl(): string
      */
     public function getOdcUrl(string $set): string
     {
-        return sprintf('%s_lodata/%s.odc', ServiceProvider::endpoint(), $set);
+        return sprintf('%s_lodata/%s.odc', $this->getEndpoint(), $set);
     }
 
     /**
@@ -370,6 +372,6 @@ public function getOdcUrl(string $set): string
      */
     public function getOpenApiUrl(): string
     {
-        return ServiceProvider::endpoint().'openapi.json';
+        return $this->getEndpoint().'openapi.json';
     }
 }