.. include:: /Includes.rst.txt .. _middlewares: =========== Middlewares =========== The extension provides two middlewares to achieve :ref:`solution streaming `. Both middlewares are registered for execution prior to all other middlewares. This allows to keep execution times during exception handling as low as possible. .. attention:: If you register additional middlewares on your own, make sure they don't conflict with the middlewares provided by this extension. Otherwise, exception handling may not be handled properly. .. _tx-solver-ping: Ping middleware =============== This middleware is used to determine whether :ref:`solution streaming ` is generally available. It is requested on error pages to decide about the used :ref:`type of problem solving `. - :aspect:`Route path:` :samp:`/tx_solver/ping` - :aspect:`Content type:` `text/event-stream` This middleware returns an `event stream `__ response. The following events are emitted: .. _ping-event-close: `close` ------- Closes the response. This event does not send any data. .. _tx-solver-solution: Solution middleware =================== If :ref:`solution streaming ` is possible, this middlewares provides the solution stream. As this can trigger expensive requests to OpenAI, the middleware is protected by a basic authentication layer. - :aspect:`Route path:` :samp:`/tx_solver/solution` - :aspect:`Content type:` `text/event-stream` - :aspect:`Required parameters`: .. confval:: exception :Required: true :type: string Cache identifier of the exception for which a solution is to provide. This identifier is returned when calling :php:meth:`EliasHaeussler\\Typo3Solver\\Cache\\ExceptionsCache::set` or :php:meth:`EliasHaeussler\\Typo3Solver\\Cache\\ExceptionsCache::getIdentifier`. .. note:: If no cache entry exists for the given identifier, an exception is thrown. .. _tx-solver-solution-hash: .. confval:: hash :Required: true :type: string One-time stream hash used to authenticate the current request against a previously registered hash. Read more at :ref:`stream-authentication` to learn about how this parameter is generated. .. attention:: If no stream hash is given or it the given hash is not valid, an exception is thrown. This middleware returns an `event stream `__ response. The following events are emitted: .. _solution-event-solutionDelta: `solutionDelta` --------------- Sends the current solution delta. Data for this event is generated by the :php:class:`EliasHaeussler\\Typo3Solver\\Formatter\\WebStreamFormatter`. It is passed as JSON string and contains the following properties: .. confval:: data :type: object Contains solution metadata. .. confval:: model :type: string The used OpenAI model. This normally matches the configured :ref:`model `. .. confval:: numberOfChoices :type: int The number of choices provided by the current solution. This normally matches the configured :ref:`number of completions `. .. confval:: numberOfPendingChoices :type: int The number of choices whose generation is not finished yet. As soon as this value is :php:`0`, the solution stream is finished. .. confval:: prompt :type: string The prompt used to generate the solution. .. confval:: content :type: string The current solution delta as formatted string. .. note:: Contains only the solution list, omitting all other components such as header and prompt. Read more at :php:class:`EliasHaeussler\\Typo3Solver\\Formatter\\WebStreamFormatter`. .. _solution-event-solutionError: `solutionError` --------------- This event is emitted once an exception is thrown during solution generation. Event data is passed as JSON string and contains the following properties: .. confval:: data :type: object Contains exception metadata. .. confval:: message :type: string The exception message. .. confval:: code :type: int The exception code. .. confval:: content :type: string The formatted exception, ready to replace the solution container on error pages. .. _solution-event-solutionFinished: `solutionFinished` ------------------ Reports the successfully finished solution stream. This event does not send any data. .. _stream-authentication: Stream authentication ===================== When using the :ref:`solution middleware `, a basic authentication layer is processed. This is to avoid that requests to OpenAI are triggered deliberately. The authentication layer basically checks if a :ref:`stream hash ` is given as query parameter and validates it against a list of previously registered hashes. If the parameter is omitted, authentication fails. A stream hash can be registered by calling :php:meth:`EliasHaeussler\\Typo3Solver\\Formatter\\Authentication\\StreamAuthentication::register`. It generates a unique hash and writes it to a transient file. This file is then looked up on request by calling :php:meth:`EliasHaeussler\\Typo3Solver\\Formatter\\Authentication\\StreamAuthentication::authenticate`. If the hash is registered, it is removed from the transient file and authentication is passed successfully. .. note:: The list of registered stream hashes is written to :file:`var/transient/tx_solver/stream_auth.txt`. .. seealso:: View the sources on GitHub: - `PingMiddleware `__ - `SolutionMiddleware `__ - `StreamAuthentication `__ - `Middleware registration `__