|
| 1 | +.. |.running-in-fastapi| replace:: Running in FastAPI |
| 2 | +.. _.running-in-fastapi: https://shapeshifter-uftp.readthedocs.io/en/latest/README.html#running-in-fastapi |
| 3 | +.. |.running-in-flask| replace:: Running in Flask |
| 4 | +.. _.running-in-flask: https://shapeshifter-uftp.readthedocs.io/en/latest/README.html#running-in-flask |
| 5 | + |
| 6 | + |
1 | 7 | Shapeshifter library for Python |
2 | 8 | =============================== |
3 | 9 |
|
@@ -39,12 +45,225 @@ If you want to develop shapeshifter-uftp, you can fork or clone this repository |
39 | 45 | $ pytest . |
40 | 46 |
|
41 | 47 |
|
42 | | -Getting Started |
43 | | ---------------- |
| 48 | +Running the Shapeshifter Service |
| 49 | +================================ |
| 50 | + |
| 51 | +The shapeshifter protocol requires you to run a server that can receive HTTP POST requests. You have the following options. |
| 52 | + |
| 53 | +- If you already have a **FastAPI** application and you'd like to run the Shapeshifter service inside that application, see |.running-in-fastapi|_. |
| 54 | + |
| 55 | +- If you already have a **Flask** application and you'd like to run the Shapeshifter service inside that, see |.running-in-flask|_. |
| 56 | + |
| 57 | +- If you don't have an existing application, or you want to run the Shapeshifter interface stand alone (perhaps inside its own Docker container), see Running stand-alone. Since the service is implemented as a standard WSGI service, you can choose several web servers like nginx, apache2 or gunicorn, which all support WSGI interfaces. |
| 58 | + |
| 59 | + |
| 60 | +.. _running-in-fastapi: |
| 61 | + |
| 62 | +Running in FastAPI |
| 63 | +------------------ |
| 64 | + |
| 65 | +To run the module in FastAPI, you can use the ``.app`` property on your instance of the Shapeshifter service, like so: |
| 66 | + |
| 67 | +.. code-block:: python3 |
| 68 | +
|
| 69 | + from a2wsgi import WSGIMiddleware |
| 70 | + from fastapi import FastAPI |
| 71 | +
|
| 72 | + from shapeshifter_uftp.service import ShapeshifterAgrService |
| 73 | +
|
| 74 | +
|
| 75 | + class MyShapeshifterService(ShapeshifterAgrService): |
| 76 | + # Your implementation of the service goes here, see next section |
| 77 | + ... |
| 78 | +
|
| 79 | +
|
| 80 | + # Create an instance of the Shapeshifter Service |
| 81 | + shapeshifter_service = MyShapeshifterService(..., path="/api/v3/message") |
| 82 | +
|
| 83 | + # Your existing FastAPI application |
| 84 | + app = FastAPI() |
| 85 | +
|
| 86 | + # Mount the Shapeshifte service inside your existing FastAPI application |
| 87 | + app.mount("/shapeshifter", shapeshifter_service.app) |
| 88 | +
|
| 89 | + ... |
| 90 | +
|
| 91 | +Note that the full path will be the mount point (``/shapeshifter``) plus the ``path`` defined in the MyShapeshifterService consructor (in this case, ``/api/v3/message``). |
| 92 | + |
| 93 | + |
| 94 | +.. _running-in-flask: |
| 95 | + |
| 96 | +Running in Flask |
| 97 | +---------------- |
| 98 | + |
| 99 | +To run the module as part of an existing Flask application, wrap your existing application in a ``DispatcherMiddleware`` like so: |
| 100 | + |
| 101 | +.. code-block:: python3 |
| 102 | +
|
| 103 | + from flask import Flask, DispatcherMiddleware |
| 104 | +
|
| 105 | + from shapeshifter_uftp.service import ShapeshifterAgrService |
| 106 | +
|
| 107 | +
|
| 108 | + class MyShapeshifterService(ShapeshifterAgrService): |
| 109 | + # Your implementation of the service goes here, see next section |
| 110 | + ... |
| 111 | +
|
| 112 | + my_app = Flask(__name__) |
| 113 | +
|
| 114 | + shapeshifter_service = MyShapeshifterService(..., path="/api/v3/message") |
| 115 | +
|
| 116 | + app = DispatcherMiddleware( |
| 117 | + my_app, |
| 118 | + {"/shapeshifter": shapeshifter_service} |
| 119 | + ) |
| 120 | +
|
| 121 | +Note that the full path will be the mount point (``/shapeshifter``) plus the ``path`` defined in the MyShapeshifterService consructor (in this case, ``/api/v3/message``). |
| 122 | + |
| 123 | + |
| 124 | +Running stand-alone |
| 125 | +------------------- |
| 126 | + |
| 127 | +To run the module completely stand-alone, you can use one of these following options. |
| 128 | + |
| 129 | +Standard library wsgiref.simple_server |
| 130 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 131 | + |
| 132 | +This is a build-in function, and you can simply use: |
| 133 | + |
| 134 | +.. code-block:: python3 |
| 135 | +
|
| 136 | + from shapeshifter_uftp.service import ShapeshifterAgrService |
| 137 | +
|
| 138 | +
|
| 139 | + class MyShapeshifterService(ShapeshifterAgrService): |
| 140 | + # Your implementation of the service goes here, see next section |
| 141 | + ... |
| 142 | +
|
| 143 | + service = MyShapeshifterService(...) |
| 144 | + service.run() |
| 145 | +
|
| 146 | +
|
| 147 | +You can customize the host, port and path from their defaults of ``'0.0.0.0'`` and ``8080`` and ``/shapeshifter/api/v3/message``. It is recommended that you leave the ``path`` to the default value, as that is the convention for Shapeshifter servers. |
| 148 | + |
| 149 | + |
| 150 | +Using apache httpd |
| 151 | +~~~~~~~~~~~~~~~~~~ |
| 152 | + |
| 153 | +You should use ``mod_wsgi``. For a python module like this, stored in the directory ``/app/main.py`` (as would be conventional in, say , a Docker image): |
| 154 | + |
| 155 | +.. code-block:: python3 |
| 156 | +
|
| 157 | + from shapeshifter_uftp.service import ShapeshifterAgrService |
| 158 | +
|
| 159 | + class MyShapeshifterService(ShapeshifterAgrService): |
| 160 | + # Your implementation of the service goes here, see next section |
| 161 | + ... |
| 162 | +
|
| 163 | + service = MyShapeshifterService(..., path="/api/v3/message") |
| 164 | +
|
| 165 | +You would point the apache2 webserver to it like so: |
| 166 | + |
| 167 | +.. code-block:: apacheconf |
| 168 | +
|
| 169 | + <VirtualHost *:80> |
| 170 | +
|
| 171 | + ServerName www.example.com |
| 172 | +
|
| 173 | + WSGIPythonHome /app/.venv/bin/python |
| 174 | + WSGIScriptAlias /shapeshifter /app/main.py |
| 175 | + WSGICallableObject service |
| 176 | +
|
| 177 | + <Directory /app> |
| 178 | + Require all granted |
| 179 | + </Directory> |
| 180 | +
|
| 181 | + </VirtualHost> |
| 182 | +
|
| 183 | +The directive ``WSGIPythonHome`` sets the location of the python interpreter to use. In this example, a uv-like ``venv`` is assumed. |
| 184 | + |
| 185 | +The directive ``WSGIScriptAlias`` takes two arguments: |
| 186 | + |
| 187 | +- The mount path (``/shapeshifter``) |
| 188 | +- The location of the python module containing the wsgi callable (``/app/main.py``) |
| 189 | + |
| 190 | +The directive ``WSGICallableObject`` takes one argument: |
| 191 | + |
| 192 | +- The name of the callable object. In the case of Shapeshifter-UFTP, this is the name you gave to your instance of your service subclass. |
| 193 | + |
| 194 | +You may need to enable ``mod_wsgi`` using ``a2enmod wsgi`` or other methods. |
| 195 | + |
| 196 | +If you are running apache exposed to the internet directly (and not in a Docker image behind some other infrastructure), you should use HTTPS on port 443, using the ``SSLEngine`` directives. |
| 197 | + |
| 198 | + |
| 199 | +Using gunicorn |
| 200 | +~~~~~~~~~~~~~~ |
| 201 | + |
| 202 | +A simple Python webserver that uses WSGI: |
| 203 | + |
| 204 | + |
| 205 | +.. code-block:: python3 |
| 206 | +
|
| 207 | + # main.py |
| 208 | + from shapeshifter_uftp.service import ShapeshifterAgrService |
| 209 | +
|
| 210 | + class MyShapeshifterService(ShapeshifterAgrService): |
| 211 | + # Your implementation of the service goes here, see next section |
| 212 | + ... |
| 213 | +
|
| 214 | + service = MyShapeshifterService(...) |
| 215 | +
|
| 216 | +Then run it like so: |
| 217 | + |
| 218 | +.. code-block:: shell |
| 219 | +
|
| 220 | + gunicorn main:service |
| 221 | +
|
| 222 | +
|
| 223 | +
|
| 224 | +Implementing your Shapeshifter Service |
| 225 | +====================================== |
44 | 226 |
|
45 | 227 | Shapehifter always requires the use of a Client and a Service, because all responses are asynchronous. |
46 | 228 |
|
47 | | -You choose the server class based on your role in the Shapeshifter conversation. If you are an Aggregator (also known as a CSP), you can use this setup: |
| 229 | +You choose the server class based on your role in the Shapeshifter conversation, and subclass the abstract implementation of the appropriate service. You then add implementations for each of the messages that you can receive, in order to post-process them according to you own business logic. |
| 230 | + |
| 231 | +This is an overview of the roles, the base class, and the methods you must implement: |
| 232 | + |
| 233 | + |
| 234 | ++------+------------------------+----------------------------------------------------------------------------------------------+ |
| 235 | +| Role | Base class | Methods to implement | |
| 236 | ++======+========================+==============================================================================================+ |
| 237 | +| AGR | ShapeshifterAgrService | * ``process_d_prognosis_response(self, message: DPrognosisResponse)`` | |
| 238 | +| | | * ``process_flex_request(self, message: FlexRequest)`` | |
| 239 | +| | | * ``process_flex_offer_response(self, message: FlexOfferResponse)`` | |
| 240 | +| | | * ``process_flex_offer_revocation_response(self, message: FlexOfferRevocationResponse)`` | |
| 241 | +| | | * ``process_flex_order(self, message: FlexOrder)`` | |
| 242 | +| | | * ``process_flex_reservation_update(self, message: FlexReservationUpdate)`` | |
| 243 | +| | | * ``process_flex_settlement(self, message: FlexSettlement)`` | |
| 244 | +| | | * ``process_metering_response(self, message: MeteringResponse)`` | |
| 245 | +| | | * ``process_agr_portfolio_query_response(self, message: AgrPortfolioQueryResponse)`` | |
| 246 | +| | | * ``process_agr_portfolio_update_response(self, message: AgrPortfolioUpdateResponse)`` | |
| 247 | ++------+------------------------+----------------------------------------------------------------------------------------------+ |
| 248 | +| DSO | ShapeshifterDsoService | * ``process_d_prognosis(self, message: DPrognosis)`` | |
| 249 | +| | | * ``process_flex_request_response(self, message: FlexRequestResponse)`` | |
| 250 | +| | | * ``process_flex_offer(self, message: FlexOffer)`` | |
| 251 | +| | | * ``process_flex_order_response(self, message: FlexOrderResponse)`` | |
| 252 | +| | | * ``process_flex_offer_revocation(self, message: FlexOfferRevocation)`` | |
| 253 | +| | | * ``process_flex_reservation_update_response(self, message: FlexReservationUpdateResponse)`` | |
| 254 | +| | | * ``process_flex_settlement_response(self, message: FlexSettlementResponse)`` | |
| 255 | +| | | * ``process_dso_portfolio_query_response(self, message: DsoPortfolioQueryResponse)`` | |
| 256 | +| | | * ``process_dso_portfolio_update_response(self, message: DsoPortfolioUpdateResponse)`` | |
| 257 | +| | | * ``process_metering(self, message: Metering)`` | |
| 258 | ++------+------------------------+----------------------------------------------------------------------------------------------+ |
| 259 | +| CRO | ShapshifterCroService | * ``process_agr_portfolio_query(self, message: AgrPortfolioQuery)`` | |
| 260 | +| | | * ``process_agr_portfolio_update(self, message: AgrPortfolioUpdate)`` | |
| 261 | +| | | * ``process_dso_portfolio_query(self, message: DsoPortfolioQuery)`` | |
| 262 | +| | | * ``process_dso_portfolio_update(self, message: DsoPortfolioQuery)`` | |
| 263 | ++------+------------------------+----------------------------------------------------------------------------------------------+ |
| 264 | + |
| 265 | + |
| 266 | +If you are an Aggregator (also known as a CSP), you can use this setup: |
48 | 267 |
|
49 | 268 | .. code-block:: python3 |
50 | 269 |
|
@@ -231,3 +450,4 @@ To use OAuth in outgoing requests, you can use the provided OAuthClient class. T |
231 | 450 |
|
232 | 451 |
|
233 | 452 | Similarly, if you have a Service instance that dynamically needs to retrieve the OAuth information for each different recipient server, you can provide an ``oauth_lookup_function`` that takes a ``(sender_domain, sender_role)`` and returns an instance of OAuthClient. |
| 453 | + |
0 commit comments