1#  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
  2#  ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
  3#  ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
  4#  ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
  5#  ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
  6#  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
  7#  ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
  8#  ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
  9#  ┃ This file is part of the Perspective library, distributed under the terms ┃
 10#  ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 11#  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 12
 13from tornado.websocket import WebSocketHandler, WebSocketClosedError
 14from tornado.ioloop import IOLoop
 15import perspective
 16
 17__doc__ = """
 18Perspective ships with a pre-built Tornado handler that makes integration with
 19`tornado.websockets` extremely easy. This allows you to run an instance of
 20`Perspective` on a server using Python, open a websocket to a `Table`, and
 21access the `Table` in JavaScript and through `<perspective-viewer>`. All
 22instructions sent to the `Table` are processed in Python, which executes the
 23commands, and returns its output through the websocket back to Javascript.
 24
 25### Python setup
 26
 27To use the handler, we need to first have a `Server`, a `Client` and an instance
 28of a `Table`:
 29
 30```python
 31SERVER = Server()
 32CLIENT = SERVER.new_local_client()
 33```
 34
 35Once the server has been created, create a `Table` instance with a name. The
 36name that you host the table under is important — it acts as a unique accessor
 37on the JavaScript side, which will look for a Table hosted at the websocket with
 38the name you specify.
 39
 40```python
 41TABLE = client.table(data, name="data_source_one")
 42```
 43
 44After the server and table setup is complete, create a websocket endpoint and
 45provide it a reference to `PerspectiveTornadoHandler`. You must provide the
 46configuration object in the route tuple, and it must contain
 47`"perspective_server"`, which is a reference to the `Server` you just created.
 48
 49```python
 50from perspective.handlers.tornado import PerspectiveTornadoHandler
 51
 52app = tornado.web.Application([
 53
 54    # ... other handlers ...
 55
 56    # Create a websocket endpoint that the client JavaScript can access
 57    (r"/websocket", PerspectiveTornadoHandler, {"perspective_server": SERVER, "check_origin": True})
 58])
 59```
 60
 61Optionally, the configuration object can also include `check_origin`, a boolean
 62that determines whether the websocket accepts requests from origins other than
 63where the server is hosted. See
 64[Tornado docs](https://www.tornadoweb.org/en/stable/websocket.html#tornado.websocket.WebSocketHandler.check_origin)
 65for more details.
 66
 67### JavaScript setup
 68
 69Once the server is up and running, you can access the Table you just hosted
 70using `perspective.websocket` and `open_table()`. First, create a client that
 71expects a Perspective server to accept connections at the specified URL:
 72
 73```javascript
 74const websocket = await perspective.websocket("ws://localhost:8888/websocket");
 75```
 76
 77Next open the `Table` we created on the server by name:
 78
 79```javascript
 80const table = await websocket.open_table("data_source_one");
 81```
 82
 83`table` is a proxy for the `Table` we created on the server. All operations that
 84are possible through the JavaScript API are possible on the Python API as well,
 85thus calling `view()`, `schema()`, `update()` etc. on `const table` will pass
 86those operations to the Python `Table`, execute the commands, and return the
 87result back to JavaScript. Similarly, providing this `table` to a
 88`<perspective-viewer>` instance will allow virtual rendering:
 89
 90```javascript
 91await viewer.load(table);
 92```
 93
 94`perspective.websocket` expects a Websocket URL where it will send instructions.
 95When `open_table` is called, the name to a hosted Table is passed through, and a
 96request is sent through the socket to fetch the Table. No actual `Table`
 97instance is passed inbetween the runtimes; all instructions are proxied through
 98websockets.
 99
100This provides for great flexibility — while `Perspective.js` is full of
101features, browser WebAssembly runtimes currently have some performance
102restrictions on memory and CPU feature utilization, and the architecture in
103general suffers when the dataset itself is too large to download to the client
104in full.
105
106The Python runtime does not suffer from memory limitations, utilizes Apache
107Arrow internal threadpools for threading and parallel processing, and generates
108architecture optimized code, which currently makes it more suitable as a
109server-side runtime than `node.js`.
110"""
111
112
113class PerspectiveTornadoHandler(WebSocketHandler):
114    """`PerspectiveTornadoHandler` is a `perspective.Server` API as a `tornado`
115    websocket handler.
116
117    Use it inside `tornado` routing to create a `perspective.Server` that can
118    connect to a JavaScript (Wasm) `Client`, providing a virtual interface to
119    the `Server`'s resources for e.g. `<perspective-viewer>`.
120
121    You may need to increase the `websocket_max_message_size` kwarg
122    to the `tornado.web.Application` constructor, as well as provide the
123    `max_buffer_size` optional arg, for large datasets.
124
125    # Arguments
126
127    -   `loop`: An optional `IOLoop` instance to use for scheduling IO calls,
128        defaults to `IOLoop.current()`.
129    -   `executor`: An optional executor for scheduling `perspective.Server`
130        message processing calls from websocket `Client`s.
131
132    # Examples
133
134    >>> server = psp.Server()
135    >>> client = server.new_local_client()
136    >>> client.table(pd.read_csv("superstore.csv"), name="data_source_one")
137    >>> app = tornado.web.Application([
138    ...     (r"/", MainHandler),
139    ...     (r"/websocket", PerspectiveTornadoHandler, {
140    ...         "perspective_server": server,
141    ...     })
142    ... ])
143    """
144
145    def check_origin(self, origin):
146        return True
147
148    def initialize(
149        self,
150        perspective_server=perspective.GLOBAL_SERVER,
151        loop=None,
152        executor=None,
153        max_buffer_size=None,
154    ):
155        self.server = perspective_server
156        self.loop = loop or IOLoop.current()
157        self.executor = executor
158        if max_buffer_size is not None:
159            self.request.connection.stream.max_buffer_size = max_buffer_size
160
161    def open(self):
162        def write(msg):
163            try:
164                self.write_message(msg, binary=True)
165            except WebSocketClosedError:
166                self.close()
167
168        def send_response(msg):
169            self.loop.add_callback(write, msg)
170
171        self.session = self.server.new_session(send_response)
172
173    def on_close(self) -> None:
174        self.session.close()
175        del self.session
176
177    def on_message(self, msg: bytes):
178        if not isinstance(msg, bytes):
179            return
180
181        if self.executor is None:
182            self.session.handle_request(msg)
183        else:
184            self.executor.submit(self.session.handle_request, msg)