HTTP API: prototype review process - prototype now live in "develop"

As promised, I've moved the code over from carlbrown/HTTPSketch to
swift-server/http into a "develop" branch:
        GitHub - swift-server/http: Historical HTTP API - please use https://github.com/swift-server/async-http-client instead

There's been three minor changes:
I've updated the licence to match the Swift.org licence and added
copyright headers
I've added a API.md file to describe what the current API in the branch is
Carl has moved SimpleResponseCreator into Tests

The next step is to go through a staged review. As its WWDC/AltConf/etc
next week a number of people will be busy, as such it doesn't make sense
to have a strict schedule until after next week. Having said that, we
should try to make progress and close down/agree on some of the types if
we can.

Paulo: As an relatively small starting point, do you want to raise a PR
to discuss making HTTPVersion a struct?

If can close that down it might make sense to then move onto HTTPMethod
and HTTPResponseStatus/HTTPStatus as those are again relatively small and
we might be able to close them out during the busy week.

Chris

···

From: Chris Bailey via swift-server-dev <swift-server-dev@swift.org>
To: <swift-server-dev@swift.org>
Date: 30/05/2017 19:13
Subject: [swift-server-dev] HTTP API: prototype review process
Sent by: swift-server-dev-bounces@swift.org

I've had some discussions with Paulo and David Ask offline, and below is
the proposal from Paulo on how we proceed:
Move the HTTP Sketch prototype (of Johannes' API proposal) into the
swift-server repo
This will go into a “develop” branch rather than "master", but will have a
MVP semver tag so it can be included via SwiftPM for people to test and
benchmark with.
Have a staged review of the types and APIs
In order to make sure that we have full "review coverage", we'll structure
reviewing and reaching agreement on the types and APIs, including having
deadlines for discussion, updates and reaching a conclusion.
Reviewed types and APIs are then merged into master
Once a set of types or APIs have been reviewed, AND they build, pass tests
with at least (95%?) coverage, 100% doc coverage, have generated jazzy
docs and as well as design docs including the rationale for design
decisions.
When the full set of types and APIs have been reviewed and merged to
master, raise a Swift Evolution Proposal
Once there is a full implementation in master, the API spec will go
forward as a Swift Evolution Proposal to get feedback from the wider
community. Once the feedback from the community is included, we can look
at tagging a 1.0.0 release based on master.

We'll also document the API separately etc as suggested by Helge Heß. If
this seems like a reasonable approach, we'll move the prototype code over
to the swift-server org into a "develop" branch tomorrow.

Chris
Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number
741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU
_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number
741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU

OK,

I tried to try that :-) As discussed there is no sample tool to run, so I tried

  swift test

that gives me plenty of errors, e.g.:
--—snip--
Started server on port 61788 with 4 Serial Queues of each type and 8 accept sockets
Test testHelloEndToEnd() on port 61788
Error accepting client connection: Error code: -9994(0x-270A), Software caused connection abort

Started server on port 61791 with 4 Serial Queues of each type and 8 accept sockets
Test testRequestEchoEndToEnd() on port 61791
ReaderSource Event Error: Error code: -9982(0x-26FE), Bad file descriptor
Error accepting client connection: Error code: -9994(0x-270A), Software caused connection abort
—snap—

etc. Yet I get

Test Suite 'All tests' passed at 2017-06-01 00:13:50.769.
   Executed 11 tests, with 0 failures (0 unexpected) in 0.226 (0.227) seconds

Is this expected behaviour?

Or how do you run this code? :-)

hh

···

On 31. May 2017, at 21:26, Chris Bailey via swift-server-dev <swift-server-dev@swift.org> wrote:

As promised, I've moved the code over from carlbrown/HTTPSketch to swift-server/http into a "develop" branch:
        GitHub - swift-server/http: ⚠ Historical HTTP API - please use https://github.com/swift-server/async-http-client instead

There's been three minor changes:
  • I've updated the licence to match the Swift.org licence and added copyright headers
  • I've added a API.md file to describe what the current API in the branch is
  • Carl has moved SimpleResponseCreator into Tests
The next step is to go through a staged review. As its WWDC/AltConf/etc next week a number of people will be busy, as such it doesn't make sense to have a strict schedule until after next week. Having said that, we should try to make progress and close down/agree on some of the types if we can.

Paulo: As an relatively small starting point, do you want to raise a PR to discuss making HTTPVersion a struct?

If can close that down it might make sense to then move onto HTTPMethod and HTTPResponseStatus/HTTPStatus as those are again relatively small and we might be able to close them out during the busy week.

Chris

From: Chris Bailey via swift-server-dev <swift-server-dev@swift.org>
To: <swift-server-dev@swift.org>
Date: 30/05/2017 19:13
Subject: [swift-server-dev] HTTP API: prototype review process
Sent by: swift-server-dev-bounces@swift.org

I've had some discussions with Paulo and David Ask offline, and below is the proposal from Paulo on how we proceed:
  • Move the HTTP Sketch prototype (of Johannes' API proposal) into the swift-server repo
This will go into a “develop” branch rather than "master", but will have a MVP semver tag so it can be included via SwiftPM for people to test and benchmark with.
  • Have a staged review of the types and APIs
In order to make sure that we have full "review coverage", we'll structure reviewing and reaching agreement on the types and APIs, including having deadlines for discussion, updates and reaching a conclusion.
  • Reviewed types and APIs are then merged into master
Once a set of types or APIs have been reviewed, AND they build, pass tests with at least (95%?) coverage, 100% doc coverage, have generated jazzy docs and as well as design docs including the rationale for design decisions.
  • When the full set of types and APIs have been reviewed and merged to master, raise a Swift Evolution Proposal
Once there is a full implementation in master, the API spec will go forward as a Swift Evolution Proposal to get feedback from the wider community. Once the feedback from the community is included, we can look at tagging a 1.0.0 release based on master.

We'll also document the API separately etc as suggested by Helge Heß. If this seems like a reasonable approach, we'll move the prototype code over to the swift-server org into a "develop" branch tomorrow.

Chris
Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU
_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

That's normal (or at least expected).

To make the tests run faster, I force-close the sockets at the end of each of the XCTests instead of waiting for a graceful cleanup. The Socket library sees that as an error (which it would be, if it happened under normal circumstances).

-Carl

···

On May 31, 2017, at 5:20 PM, Helge Heß via swift-server-dev <swift-server-dev@swift.org> wrote:

OK,

I tried to try that :-) As discussed there is no sample tool to run, so I tried

swift test

that gives me plenty of errors, e.g.:
--—snip--
Started server on port 61788 with 4 Serial Queues of each type and 8 accept sockets
Test testHelloEndToEnd() on port 61788
Error accepting client connection: Error code: -9994(0x-270A), Software caused connection abort

Started server on port 61791 with 4 Serial Queues of each type and 8 accept sockets
Test testRequestEchoEndToEnd() on port 61791
ReaderSource Event Error: Error code: -9982(0x-26FE), Bad file descriptor
Error accepting client connection: Error code: -9994(0x-270A), Software caused connection abort
—snap—

etc. Yet I get

Test Suite 'All tests' passed at 2017-06-01 00:13:50.769.
   Executed 11 tests, with 0 failures (0 unexpected) in 0.226 (0.227) seconds

Is this expected behaviour?

Or how do you run this code? :-)

hh

On 31. May 2017, at 21:26, Chris Bailey via swift-server-dev <swift-server-dev@swift.org> wrote:

As promised, I've moved the code over from carlbrown/HTTPSketch to swift-server/http into a "develop" branch:
       GitHub - swift-server/http: ⚠ Historical HTTP API - please use https://github.com/swift-server/async-http-client instead

There's been three minor changes:
  • I've updated the licence to match the Swift.org licence and added copyright headers
  • I've added a API.md file to describe what the current API in the branch is
  • Carl has moved SimpleResponseCreator into Tests
The next step is to go through a staged review. As its WWDC/AltConf/etc next week a number of people will be busy, as such it doesn't make sense to have a strict schedule until after next week. Having said that, we should try to make progress and close down/agree on some of the types if we can.

Paulo: As an relatively small starting point, do you want to raise a PR to discuss making HTTPVersion a struct?

If can close that down it might make sense to then move onto HTTPMethod and HTTPResponseStatus/HTTPStatus as those are again relatively small and we might be able to close them out during the busy week.

Chris

From: Chris Bailey via swift-server-dev <swift-server-dev@swift.org>
To: <swift-server-dev@swift.org>
Date: 30/05/2017 19:13
Subject: [swift-server-dev] HTTP API: prototype review process
Sent by: swift-server-dev-bounces@swift.org

I've had some discussions with Paulo and David Ask offline, and below is the proposal from Paulo on how we proceed:
  • Move the HTTP Sketch prototype (of Johannes' API proposal) into the swift-server repo
This will go into a “develop” branch rather than "master", but will have a MVP semver tag so it can be included via SwiftPM for people to test and benchmark with.
  • Have a staged review of the types and APIs
In order to make sure that we have full "review coverage", we'll structure reviewing and reaching agreement on the types and APIs, including having deadlines for discussion, updates and reaching a conclusion.
  • Reviewed types and APIs are then merged into master
Once a set of types or APIs have been reviewed, AND they build, pass tests with at least (95%?) coverage, 100% doc coverage, have generated jazzy docs and as well as design docs including the rationale for design decisions.
  • When the full set of types and APIs have been reviewed and merged to master, raise a Swift Evolution Proposal
Once there is a full implementation in master, the API spec will go forward as a Swift Evolution Proposal to get feedback from the wider community. Once the feedback from the community is included, we can look at tagging a 1.0.0 release based on master.

We'll also document the API separately etc as suggested by Helge Heß. If this seems like a reasonable approach, we'll move the prototype code over to the swift-server org into a "develop" branch tomorrow.

Chris
Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU
_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

*Paulo:* As an relatively small starting point, do you want to

raise a PR to discuss making HTTPVersion a struct?

OK! I'll send a PR tomorow!

···

On 31 May 2017 at 19:27, Carl Brown via swift-server-dev < swift-server-dev@swift.org> wrote:

That's normal (or at least expected).

To make the tests run faster, I force-close the sockets at the end of each
of the XCTests instead of waiting for a graceful cleanup. The Socket
library sees that as an error (which it would be, if it happened under
normal circumstances).

-Carl

> On May 31, 2017, at 5:20 PM, Helge Heß via swift-server-dev < > swift-server-dev@swift.org> wrote:
>
> OK,
>
> I tried to try that :-) As discussed there is no sample tool to run, so
I tried
>
> swift test
>
> that gives me plenty of errors, e.g.:
> --—snip--
> Started server on port 61788 with 4 Serial Queues of each type and 8
accept sockets
> Test testHelloEndToEnd() on port 61788
> Error accepting client connection: Error code: -9994(0x-270A), Software
caused connection abort
> …
> Started server on port 61791 with 4 Serial Queues of each type and 8
accept sockets
> Test testRequestEchoEndToEnd() on port 61791
> ReaderSource Event Error: Error code: -9982(0x-26FE), Bad file descriptor
> Error accepting client connection: Error code: -9994(0x-270A), Software
caused connection abort
> —snap—
>
> etc. Yet I get
>
> Test Suite 'All tests' passed at 2017-06-01 00:13:50.769.
> Executed 11 tests, with 0 failures (0 unexpected) in 0.226
(0.227) seconds
>
> Is this expected behaviour?
>
> Or how do you run this code? :-)
>
> hh
>
>
> On 31. May 2017, at 21:26, Chris Bailey via swift-server-dev < > swift-server-dev@swift.org> wrote:
>> As promised, I've moved the code over from carlbrown/HTTPSketch to
swift-server/http into a "develop" branch:
>> GitHub - swift-server/http: ⚠ Historical HTTP API - please use https://github.com/swift-server/async-http-client instead
>>
>> There's been three minor changes:
>> • I've updated the licence to match the Swift.org licence and
added copyright headers
>> • I've added a API.md file to describe what the current API in the
branch is
>> • Carl has moved SimpleResponseCreator into Tests
>> The next step is to go through a staged review. As its WWDC/AltConf/etc
next week a number of people will be busy, as such it doesn't make sense to
have a strict schedule until after next week. Having said that, we should
try to make progress and close down/agree on some of the types if we can.
>>
>> Paulo: As an relatively small starting point, do you want to
raise a PR to discuss making HTTPVersion a struct?
>>
>> If can close that down it might make sense to then move onto HTTPMethod
and HTTPResponseStatus/HTTPStatus as those are again relatively small and
we might be able to close them out during the busy week.
>>
>> Chris
>>
>>
>>
>>
>> From: Chris Bailey via swift-server-dev <
swift-server-dev@swift.org>
>> To: <swift-server-dev@swift.org>
>> Date: 30/05/2017 19:13
>> Subject: [swift-server-dev] HTTP API: prototype review process
>> Sent by: swift-server-dev-bounces@swift.org
>>
>>
>>
>> I've had some discussions with Paulo and David Ask offline, and below
is the proposal from Paulo on how we proceed:
>> • Move the HTTP Sketch prototype (of Johannes' API proposal) into
the swift-server repo
>> This will go into a “develop” branch rather than "master", but will
have a MVP semver tag so it can be included via SwiftPM for people to test
and benchmark with.
>> • Have a staged review of the types and APIs
>> In order to make sure that we have full "review coverage", we'll
structure reviewing and reaching agreement on the types and APIs, including
having deadlines for discussion, updates and reaching a conclusion.
>> • Reviewed types and APIs are then merged into master
>> Once a set of types or APIs have been reviewed, AND they build, pass
tests with at least (95%?) coverage, 100% doc coverage, have generated
jazzy docs and as well as design docs including the rationale for design
decisions.
>> • When the full set of types and APIs have been reviewed and
merged to master, raise a Swift Evolution Proposal
>> Once there is a full implementation in master, the API spec will go
forward as a Swift Evolution Proposal to get feedback from the wider
community. Once the feedback from the community is included, we can look at
tagging a 1.0.0 release based on master.
>>
>> We'll also document the API separately etc as suggested by Helge Heß.
If this seems like a reasonable approach, we'll move the prototype code
over to the swift-server org into a "develop" branch tomorrow.
>>
>> Chris
>> Unless stated otherwise above:
>> IBM United Kingdom Limited - Registered in England and Wales with
number 741598.
>> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU_______________________________________________
>> swift-server-dev mailing list
>> swift-server-dev@swift.org
>> https://lists.swift.org/mailman/listinfo/swift-server-dev
>>
>>
>>
>> Unless stated otherwise above:
>> IBM United Kingdom Limited - Registered in England and Wales with
number 741598.
>> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU
>> _______________________________________________
>> swift-server-dev mailing list
>> swift-server-dev@swift.org
>> https://lists.swift.org/mailman/listinfo/swift-server-dev
>
> _______________________________________________
> swift-server-dev mailing list
> swift-server-dev@swift.org
> https://lists.swift.org/mailman/listinfo/swift-server-dev

_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev

Where does the error printing happen? If it's in Swift, can we suppress it so that ti doesn't confuse people who are running the tests in future?

Alex

···

On 31 May 2017, at 23:27, Carl Brown via swift-server-dev <swift-server-dev@swift.org> wrote:

That's normal (or at least expected).

To make the tests run faster, I force-close the sockets at the end of each of the XCTests instead of waiting for a graceful cleanup. The Socket library sees that as an error (which it would be, if it happened under normal circumstances).

Where does the error printing happen? If it's in Swift, can we suppress it so that ti doesn't confuse people who are running the tests in future?

Alex

···

On 31 May 2017, at 23:27, Carl Brown via swift-server-dev <swift-server-dev@swift.org> wrote:

That's normal (or at least expected).

To make the tests run faster, I force-close the sockets at the end of each of the XCTests instead of waiting for a graceful cleanup. The Socket library sees that as an error (which it would be, if it happened under normal circumstances).

It's in Swift, but it's several layers of encapsulation removed from the tests, and in many different places.

I started an implementation where there was a boolean flag that indicated that the socket had been forced-closed and that errors needed to be suppressed, and that flag was propagated down the call stack, but it turned out to make the code a lot harder to read.

For this stage of the prototype, we thought that shorter and cleaner we could get the code, the easier it would be to discuss and share with the community.

If the consensus is that the community thinks the trade off is worth it, it's not very hard to put in, but it complicates all the development going forward.

What does everyone think?

-Carl

···

On Jun 1, 2017, at 3:35 AM, Alex Blewitt <alblue@apple.com> wrote:

On 31 May 2017, at 23:27, Carl Brown via swift-server-dev <swift-server-dev@swift.org> wrote:

That's normal (or at least expected).

To make the tests run faster, I force-close the sockets at the end of each of the XCTests instead of waiting for a graceful cleanup. The Socket library sees that as an error (which it would be, if it happened under normal circumstances).

Where does the error printing happen? If it's in Swift, can we suppress it so that ti doesn't confuse people who are running the tests in future?

Alex

I think that's irrelevant, at this point.

···

On Thu, Jun 1, 2017, 11:57 Carl Brown via swift-server-dev < swift-server-dev@swift.org> wrote:

> On Jun 1, 2017, at 3:35 AM, Alex Blewitt <alblue@apple.com> wrote:
>
>> On 31 May 2017, at 23:27, Carl Brown via swift-server-dev < > swift-server-dev@swift.org> wrote:
>>
>> That's normal (or at least expected).
>>
>> To make the tests run faster, I force-close the sockets at the end of
each of the XCTests instead of waiting for a graceful cleanup. The Socket
library sees that as an error (which it would be, if it happened under
normal circumstances).
>
> Where does the error printing happen? If it's in Swift, can we suppress
it so that ti doesn't confuse people who are running the tests in future?
>
> Alex

It's in Swift, but it's several layers of encapsulation removed from the
tests, and in many different places.

I started an implementation where there was a boolean flag that indicated
that the socket had been forced-closed and that errors needed to be
suppressed, and that flag was propagated down the call stack, but it turned
out to make the code a lot harder to read.

For this stage of the prototype, we thought that shorter and cleaner we
could get the code, the easier it would be to discuss and share with the
community.

If the consensus is that the community thinks the trade off is worth it,
it's not very hard to put in, but it complicates all the development going
forward.

What does everyone think?

-Carl
_______________________________________________
swift-server-dev mailing list
swift-server-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev