Middlewares

The extension provides two middlewares to achieve 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.

Ping middleware

This middleware is used to determine whether solution streaming is generally available. It is requested on error pages to decide about the used type of problem solving.

  • Route path: /tx_solver/ping
  • Content type: text/event-stream

This middleware returns an event stream response. The following events are emitted:

close

Closes the response. This event does not send any data.

Solution middleware

If 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.

  • Route path: /tx_solver/solution
  • Content type: text/event-stream

  • Required parameters:

    exception

    exception
    Type
    string
    Required
    true

    Cache identifier of the exception for which a solution is to provide. This identifier is returned when calling \EliasHaeussler\Typo3Solver\Cache\ExceptionsCache::set or \EliasHaeussler\Typo3Solver\Cache\ExceptionsCache::getIdentifier.

    hash

    hash
    Type
    string
    Required
    true

    One-time stream hash used to authenticate the current request against a previously registered hash. Read more at Stream authentication to learn about how this parameter is generated.

This middleware returns an event stream response. The following events are emitted:

solutionDelta

Sends the current solution delta. Data for this event is generated by the \EliasHaeussler\Typo3Solver\Formatter\WebStreamFormatter. It is passed as JSON string and contains the following properties:

data

data
Type
object

Contains solution metadata.

model

model
Type
string

The used OpenAI model. This normally matches the configured model.

numberOfResponses

numberOfResponses
Type
int

The number of responses provided by the current solution. This normally matches the configured number of completions.

numberOfPendingResponses

numberOfPendingResponses
Type
int

The number of responses whose generation is not finished yet. As soon as this value is 0, the solution stream is finished.

prompt

prompt
Type
string

The prompt used to generate the solution.

content

content
Type
string

The current solution delta as formatted string.

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:

data

data
Type
object

Contains exception metadata.

message

message
Type
string

The exception message.

code

code
Type
int

The exception code.

content

content
Type
string

The formatted exception, ready to replace the solution container on error pages.

solutionFinished

Reports the successfully finished solution stream. This event does not send any data.

Stream authentication

When using the 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 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 \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 \EliasHaeussler\Typo3Solver\Formatter\Authentication\StreamAuthentication::authenticate. If the hash is registered, it is removed from the transient file and authentication is passed successfully.