Modify Handler.finished API to remove assumption all responses are one-shot.

[redvers]

NOTE: This is a breaking change.

TODO:
✅ Update Docs
✅ Release Notes
✅ Clearer Example Maybe?

Caveat:

This may be a dragon. From handler.pony:

  It is guaranteed that the call sequence is always:
                                                                                   
  - exactly once:       `apply(request_n, requestid_n)`
  - zero or more times: `chunk(data, requestid_n)`                              
  - exactly once:       `finished(requestid_n)`                                    
                    
  And so on for `requestid_(n + 1)`. Only after `finished` has been called for a   
  `RequestID`, the next request will be received by the Handler instance, there will
  be no interleaving. So it is save to keep state for the given request in a Handler between calls to `apply`
  and `finished`.                        

This raises the very real possibility that a new apply() request may come in on the same Handler while we're still doing our recursive calls to finished().

In other words, "it is safe to keep state for the given request in the Handler between calls" may no longer be true.

More investigation required.

[SeanTAllen]

@redvers I see no problem with finished getting called multiple times on the user supplied handler so long as "send finished" is only called once.

Also note, that all Handler methods take a request id. Existing code already needs to account for more than 1 request being in-flight at a time.

See:

  be send_finished(request_id: RequestID) =>
    """
    ### Verbose API

    Indicate that the response for `request_id` has been completed,
    that is, its status, headers and body have been sent.

    This will clean up resources on the session and
    might send pending pipelined responses in addition to this response.

    If this behaviour isnt called, the server might misbehave, especially
    with clients doing HTTP pipelining.
    """
    None

on session.pony.

The update to those docs you posted would be that finished is called 1 or more times. 1 time is guaranteed if you return true that you are finished, otherwise it is called until the handler indicates it is finished finishing.

[ponylang-main]

Hi @redvers,

The changelog - changed label was added to this pull request; all PRs with a changelog label need to have release notes included as part of the PR. If you haven't added release notes already, please do.

Release notes are added by creating a uniquely named file in the .release-notes directory. We suggest you call the file 81.md to match the number of this pull request.

The basic format of the release notes (using markdown) should be:

## Title

End user description of changes, why it's important,
problems it solves etc.

If a breaking change, make sure to include 1 or more
examples what code would look like prior to this change
and how to update it to work after this change.

Thanks.

[SeanTAllen]

why is the commented out?

[redvers]

Also note, that all Handler methods take a request id. Existing code already needs to account for more than 1 request being in-flight at a time.

This is the part of the documentation that made me believe that Handlers don't need to deal with multiple requests at the same time:

And so on for requestid_(n + 1). Only after finished has been called for a
RequestID, the next request will be received by the Handler instance, there
will be no interleaving. So it is save to keep state for the given request
in a Handler between calls to apply and finished.

Specifically:

there will be no interleaving.

If Handlers do need to be able to handle more than one request at a time then we likely need to clarify the documentation and modify the examples to do this.