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.

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.

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
    Required

    true

    Type

    string

    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.

    Note

    If no cache entry exists for the given identifier, an exception is thrown.

    hash
    Required

    true

    Type

    string

    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.

    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:

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
Type

object

Contains solution metadata.

model
Type

string

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

numberOfChoices
Type

int

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

numberOfPendingChoices
Type

int

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

prompt
Type

string

The prompt used to generate the solution.

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 EliasHaeussler\Typo3Solver\Formatter\WebStreamFormatter.

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
Type

object

Contains exception metadata.

message
Type

string

The exception message.

code
Type

int

The exception code.

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.

Note

The list of registered stream hashes is written to var/transient/tx_solver/stream_auth.txt.

See also

View the sources on GitHub: