Added support for Thing-wide external links

Author: Joel Collins

src/labthings/labthing.py

@@ -66,6 +66,8 @@ class LabThing:
     :type types: list of str
     :param format_flask_exceptions: JSON format all exception responses
     :type format_flask_exceptions: bool
+    :param external_links: Use external links in Thing Description where possible
+    :type external_links: bool
     :param json_encoder: JSON encoder class for the app
     """
 
@@ -78,6 +80,7 @@ def __init__(
         version: str = "0.0.0",
         types: list = None,
         format_flask_exceptions: bool = True,
+        external_links: bool = True,
         json_encoder=LabThingsJSONEncoder,
     ):
         if types is None:
@@ -136,7 +139,7 @@ def __init__(
         )
 
         # Thing description
-        self.thing_description = ThingDescription()
+        self.thing_description = ThingDescription(external_links=external_links)
 
         # JSON encoder class
         self.json_encoder = json_encoder

src/labthings/quick.py

@@ -12,6 +12,7 @@ def create_app(
     description: str = "",
     types: list = None,
     version: str = "0.0.0",
+    external_links: bool = True,
     handle_errors: bool = True,
     handle_cors: bool = True,
     flask_kwargs: dict = None,
@@ -40,6 +41,7 @@ def create_app(
     :param description: str:  (Default value = "")
     :param types: list:  (Default value = None)
     :param version: str:  (Default value = "0.0.0")
+    :param external_links: bool: Use external links in Thing Description where possible
     :param handle_errors: bool:  (Default value = True)
     :param handle_cors: bool:  (Default value = True)
     :param flask_kwargs: dict:  (Default value = None)
@@ -69,6 +71,7 @@ def create_app(
         types=types,
         version=str(version),
         format_flask_exceptions=handle_errors,
+        external_links=external_links,
     )
 
     return app, labthing

src/labthings/td.py

@@ -1,13 +1,13 @@
-from flask import url_for, request
+from flask import url_for, request, has_request_context
 
 from .views import View
 from .event import Event
 from .json.schemas import schema_to_json, rule_to_params, rule_to_path
 from .find import current_labthing
-from .utilities import get_docstring, snake_to_camel
+from .utilities import ResourceURL, get_docstring, snake_to_camel
 
 
-def view_to_thing_action_forms(rules: list, view: View):
+def view_to_thing_action_forms(rules: list, view: View, external: bool = True):
     """Build a W3C form description for an ActionView
 
     :param rules: List of Flask rules
@@ -16,6 +16,7 @@ def view_to_thing_action_forms(rules: list, view: View):
     :type view: View
     :param rules: list: 
     :param view: View: 
+    :param external: bool: Use external links where possible
     :returns: Form description
     :rtype: [dict]
 
@@ -36,7 +37,7 @@ def view_to_thing_action_forms(rules: list, view: View):
             form = {
                 "op": "invokeaction",
                 "htv:methodName": "POST",
-                "href": url,
+                "href": ResourceURL(url, external=external),
                 "contentType": content_type,
             }
             if response_content_type != content_type:
@@ -47,7 +48,7 @@ def view_to_thing_action_forms(rules: list, view: View):
     return forms
 
 
-def view_to_thing_property_forms(rules: list, view: View):
+def view_to_thing_property_forms(rules: list, view: View, external: bool = True):
     """Build a W3C form description for a PropertyView
 
     :param rules: List of Flask rules
@@ -56,6 +57,7 @@ def view_to_thing_property_forms(rules: list, view: View):
     :type view: View
     :param rules: list: 
     :param view: View: 
+    :param external: bool: Use external links where possible
     :returns: Form description
     :rtype: [dict]
 
@@ -74,7 +76,7 @@ def view_to_thing_property_forms(rules: list, view: View):
             form = {
                 "op": "readproperty",
                 "htv:methodName": "GET",
-                "href": url,
+                "href": ResourceURL(url, external=external),
                 "contentType": content_type,
             }
             forms.append(form)
@@ -85,7 +87,7 @@ def view_to_thing_property_forms(rules: list, view: View):
             form = {
                 "op": "writeproperty",
                 "htv:methodName": "PUT",
-                "href": url,
+                "href": ResourceURL(url, external=external),
                 "contentType": content_type,
             }
             forms.append(form)
@@ -96,7 +98,7 @@ def view_to_thing_property_forms(rules: list, view: View):
             form = {
                 "op": "writeproperty",
                 "htv:methodName": "POST",
-                "href": url,
+                "href": ResourceURL(url, external=external),
                 "contentType": content_type,
             }
             forms.append(form)
@@ -106,11 +108,20 @@ def view_to_thing_property_forms(rules: list, view: View):
 
 class ThingDescription:
     """ """
-    def __init__(self):
+
+    def __init__(self, external_links: bool = True):
+        # Public attributes
         self.properties = {}
         self.actions = {}
         self.events = {}
+
+        # Private attributes
         self._links = []
+
+        # Settings
+        self.external_links = external_links
+
+        # Init
         super().__init__()
 
     @property
@@ -124,7 +135,7 @@ def links(self):
                     "href": current_labthing().url_for(
                         link_description.get("view"),
                         **link_description.get("params"),
-                        _external=True,
+                        _external=self.external_links,
                     ),
                     **link_description.get("kwargs"),
                 }
@@ -150,14 +161,13 @@ def add_link(self, view, rel, kwargs=None, params=None):
 
     def to_dict(self):
         """ """
-        return {
+        td = {
             "@context": [
                 "https://www.w3.org/2019/wot/td/v1",
                 "https://iot.mozilla.org/schemas/",
             ],
             "@type": current_labthing().types,
             "id": url_for("root", _external=True),
-            "base": request.host_url,
             "title": current_labthing().title,
             "description": current_labthing().description,
             "properties": self.properties,
@@ -168,6 +178,11 @@ def to_dict(self):
             "security": "nosec_sc",
         }
 
+        if not self.external_links and has_request_context():
+            td["base"] = request.host_url
+
+        return td
+
     def event_to_thing_event(self, event: Event):
         """
 
@@ -194,8 +209,13 @@ def view_to_thing_property(self, rules: list, view: View):
                 hasattr(view, "post") or hasattr(view, "put") or hasattr(view, "delete")
             ),
             "writeOnly": not hasattr(view, "get"),
-            "links": [{"href": f"{url}"} for url in prop_urls],
-            "forms": view_to_thing_property_forms(rules, view),
+            "links": [
+                {"href": ResourceURL(url, external=self.external_links)}
+                for url in prop_urls
+            ],
+            "forms": view_to_thing_property_forms(
+                rules, view, external=self.external_links
+            ),
             "uriVariables": {},
         }
 
@@ -243,10 +263,15 @@ def view_to_thing_action(self, rules: list, view: View):
         action_description = {
             "title": getattr(view, "title", None) or view.__name__,
             "description": getattr(view, "description", None) or get_docstring(view),
-            "links": [{"href": f"{url}"} for url in action_urls],
+            "links": [
+                {"href": ResourceURL(url, external=self.external_links)}
+                for url in action_urls
+            ],
             "safe": getattr(view, "safe", False),
             "idempotent": getattr(view, "idempotent", False),
-            "forms": view_to_thing_action_forms(rules, view),
+            "forms": view_to_thing_action_forms(
+                rules, view, external=self.external_links
+            ),
         }
 
         # Look for a _params in the Action classes API Spec

src/labthings/utilities.py

@@ -1,7 +1,8 @@
 from werkzeug.http import HTTP_STATUS_CODES
-from flask import current_app
+from flask import current_app, has_request_context, request
 
 import collections.abc
+from collections import UserString
 import re
 import operator
 import sys
@@ -39,6 +40,32 @@ def stopped(self):
         return time.time() >= self.timeout_time
 
 
+class ResourceURL(UserString):
+    """
+    Takes a URL path relative to the host_url (e.g. /api/myresource),
+    and optionally prepends the host URL to generate a complete URL
+    (e.g. http://localhost:7485/api/myresource).
+    Behaves as a Python string.
+    """
+
+    def __init__(self, path: str, external: bool = True):
+        self.path = path
+        self.external = external
+        UserString.__init__(self, path)
+
+    @property
+    def data(self):
+        if self.external and has_request_context():
+            prefix = request.host_url.rstrip("/")
+        else:
+            prefix = ""
+        return prefix + self.path
+
+    @data.setter
+    def data(self, path: str):
+        self.path = path
+
+
 def http_status_message(code):
     """Maps an HTTP status code to the textual status