You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 3b15bec
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: README.rst
+222-3Lines changed: 222 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,12 +39,231 @@ If you want to develop shapeshifter-uftp, you can fork or clone this repository
39
39
$ pytest .
40
40
41
41
42
-
Getting Started
43
-
---------------
42
+
Running the Shapeshifter Service
43
+
================================
44
+
45
+
The shapeshifter protocol requires you to run a server that can receive HTTP POST requests. You have the following options.
46
+
47
+
- If you already have a **FastAPI** application and you'd like to run the Shapeshifter service inside that application, see `Running in FastAPI <#running-in-fastapi>`_.
48
+
49
+
- If you already have a **Flask** application and you'd like to run the Shapeshifter service inside that, see `Running in Flask <#running-in-flask>`_.
50
+
51
+
- 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 <#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.
52
+
53
+
54
+
.. _running-in-fastapi:
55
+
56
+
Running in FastAPI
57
+
------------------
58
+
59
+
To run the module in FastAPI, you can use the ``.app`` property on your instance of the Shapeshifter service, like so:
60
+
61
+
.. code-block:: python3
62
+
63
+
from fastapi import FastAPI
64
+
from shapeshifter_uftp.service import ShapeshifterAgrService
65
+
66
+
67
+
class MyShapeshifterService(ShapeshifterAgrService):
68
+
# Your implementation of the service goes here, see next section
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``).
84
+
85
+
86
+
.. _running-in-flask:
87
+
88
+
Running in Flask
89
+
----------------
90
+
91
+
To run the module as part of an existing Flask application, wrap your existing application in a ``DispatcherMiddleware`` like so:
92
+
93
+
.. code-block:: python3
94
+
95
+
from flask import Flask, DispatcherMiddleware
96
+
97
+
from shapeshifter_uftp.service import ShapeshifterAgrService
98
+
99
+
100
+
class MyShapeshifterService(ShapeshifterAgrService):
101
+
# Your implementation of the service goes here, see next section
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``).
114
+
115
+
116
+
.. _running-stand-alone:
117
+
118
+
Running stand-alone
119
+
-------------------
120
+
121
+
To run the module completely stand-alone, you can use one of these following options.
122
+
123
+
Standard library wsgiref.simple_server
124
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
125
+
126
+
This is a build-in function, and you can simply use:
127
+
128
+
.. code-block:: python3
129
+
130
+
from shapeshifter_uftp.service import ShapeshifterAgrService
131
+
132
+
133
+
class MyShapeshifterService(ShapeshifterAgrService):
134
+
# Your implementation of the service goes here, see next section
135
+
...
136
+
137
+
service = MyShapeshifterService(...)
138
+
service.run()
139
+
140
+
141
+
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.
142
+
143
+
144
+
Using apache httpd
145
+
~~~~~~~~~~~~~~~~~~
146
+
147
+
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):
148
+
149
+
.. code-block:: python3
150
+
151
+
# /app/main.py
152
+
153
+
from shapeshifter_uftp.service import ShapeshifterAgrService
154
+
155
+
class MyShapeshifterService(ShapeshifterAgrService):
156
+
# Your implementation of the service goes here, see next section
157
+
...
158
+
159
+
# Create an instance of your Shapeshifter service.
160
+
# This instance itself is also a WSGI-compatible callable.
161
+
service = MyShapeshifterService(..., path="/api/v3/message")
162
+
163
+
You would point the apache2 webserver to it like so:
164
+
165
+
.. code-block:: apacheconf
166
+
167
+
<VirtualHost *:80>
168
+
169
+
ServerName www.example.com
170
+
171
+
WSGIPythonHome /app/.venv/bin/python
172
+
WSGIScriptAlias /shapeshifter /app/main.py
173
+
WSGICallableObject service
174
+
175
+
<Directory /app>
176
+
Require all granted
177
+
</Directory>
178
+
179
+
</VirtualHost>
180
+
181
+
The directive ``WSGIPythonHome`` sets the location of the python interpreter to use. In this example, a uv-like ``venv`` is assumed.
182
+
183
+
The directive ``WSGIScriptAlias`` takes two arguments:
184
+
185
+
- The mount path (``/shapeshifter``)
186
+
- The location of the python module containing the wsgi callable (``/app/main.py``)
187
+
188
+
The directive ``WSGICallableObject`` takes one argument:
189
+
190
+
- 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.
191
+
192
+
You may need to enable ``mod_wsgi`` using ``a2enmod wsgi`` or other methods.
193
+
194
+
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.
195
+
196
+
197
+
Using gunicorn
198
+
~~~~~~~~~~~~~~
199
+
200
+
A simple Python webserver that uses WSGI:
201
+
202
+
203
+
.. code-block:: python3
204
+
205
+
# main.py
206
+
from shapeshifter_uftp.service import ShapeshifterAgrService
207
+
208
+
class MyShapeshifterService(ShapeshifterAgrService):
209
+
# Your implementation of the service goes here, see next section
210
+
...
211
+
212
+
# Create an instance of your Shapeshifter service.
213
+
# This instance itself is also a WSGI-compatible callable.
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:
Copy file name to clipboardExpand all lines: docs/source/api/types.rst
+2-5Lines changed: 2 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,8 +3,5 @@ Types API Reference
3
3
4
4
These objects correspond directly to the UFTP objects that are sent across the wire. You will encounter these in the messages and response when using Shapeshifter UFTP.
Copy file name to clipboardExpand all lines: docs/source/index.rst
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@
6
6
Welcome to Shapeshifter UFTP's documentation!
7
7
=============================================
8
8
9
-
This library allows you to quickly build applications that talk to Distribution System Operators, Aggregators and Common Reference Operators as defined in the UFTP Specification.
9
+
This library allows you to quickly build applications that talk to Distribution System Operators (DSO), Aggregators (AGR) and Common Reference Operators (CRO) as defined in the UFTP Specification.
0 commit comments