HTTP API Review

[Chris_Bailey]

The HTTP part of the Swift Server API project has undergone a number of
iterations and updates, and I believe its approaching the point that we
have sufficient function for use to raise a Swift Evolution "Pitch" and
give the wider user community and opportunity to try out the APIs and
provide some early feedback.

The main documentation for the HTTP API is now available via GitHub Pages
here:
        HTTP Reference
which describes the use of a "WebApp" to handle an incoming HTTPRequest
and build a response.

The main item that's missing is a minimal set of APIs to create the HTTP
server itself, and to rename the "WebApp" to something better. The
following PR from Ian Partridge proposes to do that:
        Add HTTPServer so we don't vend BlueSocketHTTP by ianpartridge · Pull Request #26 · swift-server/http · GitHub

This renames "WebApp" to "HTTPRequestHandler" provides a
"SimpleHTTPServer" implementation with start() and stop() functions. This
means you can create and run a simple server with the following:

class SimpleHandler: HTTPRequestHandling {
    func handle(request: HTTPRequest, response: HTTPResponseWriter ) ->
HTTPBodyProcessing {
        response.writeHeader(status: .ok, headers: ["Transfer-Encoding":
"chunked", "X-foo": "bar"])
        return .processBody { (chunk, stop) in
            switch chunk {
            case .chunk(let data, let finishedProcessing):
                response.writeBody(data) { _ in
                    finishedProcessing()
                }
            case .end:
                response.done()
            default:
                stop = true
                response.abort()
            }
        }
    }
}

let server = SimpleHTTPServer()

try! server.start(port: 0, handler: SimpleHandler().handle)

Please take a look and provide feedback, for example, suggesting that
SimpleHTTPServer should just be HTTPServer ;-)

Thanks,

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

[DevAndArtist (Adrian Meister)]

Hi Chris,

Well I do not participate in the server workgroup, but I do track its evolution from time to time. I Also haven’t used the new API as a library to play around with, but I had a quick glance over the API.

There are a few questions and suggestions to simplify the evolution of the server side APIs in general:

- (I haven’t tracked that particular decision) Why not calling the module `HTTP`?
- Even it the module is currently called `SwiftServerHTTP`, isn’t the HTTP type prefix redundant?
- If the Module was called `HTTP` then you could use `HTTP.Method` if you wanted or simply omit the HTTP because it would be optional.

+ I would highly suggest to include a swift lint file so that everyone who’s working on the code follows the same code style rules. (https://github.com/realm/SwiftLint\)
+ case/default is part of switch statement itself - indent violation: http/HTTPHeaders.swift at develop · swift-server/http · GitHub (there are a lot more of these)
+ use optional unwrapping instead - avoid force cast: http/HTTPHeaders.swift at develop · swift-server/http · GitHub
+ whitespace violation: http/HTTPResponse.swift at develop · swift-server/http · GitHub
+ missing whitespace for inheritance / conformance before the colon: http/HTTPResponse.swift at develop · swift-server/http · GitHub
+ use whitespaces around operators: http/HTTPResponse.swift at develop · swift-server/http · GitHub
+ use whitespaces around assigning operator: http/HTTPStreamingParser.swift at develop · swift-server/http · GitHub
+ either omit `self` as much as Swift allows or write it everywhere possible
+ probably longer than the 120 character width - choose one, either 80 or 120: http/HTTPStreamingParser.swift at develop · swift-server/http · GitHub
+ unnecessary new line: http/HTTPStreamingParser.swift at develop · swift-server/http · GitHub
+ missing back ticks around `get`: http/HTTPMethod.swift at develop · swift-server/http · GitHub
+ missing whitespace after the operator in declaration: http/HTTPResponse.swift at develop · swift-server/http · GitHub

These are a couple of things that my eyes could catch at a quick glance.

Here are the rules I’m using in a project:

opt_in_rules:
  - closure_end_indentation
  - closure_spacing
  - fatal_error_message
  - force_unwrapping
  - sorted_imports
  - operator_usage_whitespace
  - redundant_nil_coalescing
  - switch_case_on_newline
  - attributes
  - no_extension_access_modifier
  - implicit_return

# rule identifiers to exclude from running
disabled_rules: 
  - colon
  - closure_parameter_position
  - opening_brace
  - file_length
  - implicit_return

identifier_name:
  # excluded via string array
  excluded: 
    - px

large_tuple: 4

cyclomatic_complexity: 15

nesting:
  type_level: 2

trailing_whitespace:
  ignores_empty_lines: true
  ignores_comments: true

attributes:
  always_on_same_line: ["@IBAction", "@IBOutlet", "@IBInspectable"]
  always_on_line_above: ["@IBDesignable", "@UIApplicationMain", "@discardableResult", "@objc"]

···

Am 21. August 2017 um 21:54:38, Chris Bailey via swift-server-dev (swift-server-dev@swift.org) schrieb:

The HTTP part of the Swift Server API project has undergone a number of iterations and updates, and I believe its approaching the point that we have sufficient function for use to raise a Swift Evolution "Pitch" and give the wider user community and opportunity to try out the APIs and provide some early feedback.

The main documentation for the HTTP API is now available via GitHub Pages here:
HTTP Reference
which describes the use of a "WebApp" to handle an incoming HTTPRequest and build a response.

The main item that's missing is a minimal set of APIs to create the HTTP server itself, and to rename the "WebApp" to something better. The following PR from Ian Partridge proposes to do that:
Add HTTPServer so we don't vend BlueSocketHTTP by ianpartridge · Pull Request #26 · swift-server/http · GitHub

This renames "WebApp" to "HTTPRequestHandler" provides a "SimpleHTTPServer" implementation with start() and stop() functions. This means you can create and run a simple server with the following:

class SimpleHandler: HTTPRequestHandling {
func handle(request: HTTPRequest, response: HTTPResponseWriter ) -> HTTPBodyProcessing {
response.writeHeader(status: .ok, headers: ["Transfer-Encoding": "chunked", "X-foo": "bar"])
return .processBody { (chunk, stop) in
switch chunk {
case .chunk(let data, let finishedProcessing):
response.writeBody(data) { _ in
finishedProcessing()
}
case .end:
response.done()
default:
stop = true
response.abort()
}
}
}
}

let server = SimpleHTTPServer()

try! server.start(port: 0, handler: SimpleHandler().handle)

Please take a look and provide feedback, for example, suggesting that SimpleHTTPServer should just be HTTPServer ;-)

Thanks,

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

[gmosx (Georgios Moschovitis)]

Had a (very) quick look, and in general it looks OK.
One thing that bothers me in the example is this ***Handler <-> ***Handling inconsistency..

class SimpleHandler: HTTPRequestHandling

maybe something like

class WebApp: HTTPRequestHandling {
  ...
}

would make it less confusing?

-g.

[Helge_Hess1 (Helge Heß)]

Hi Chris,

Well I do not participate in the server workgroup, but I do track its evolution from time to time.

...

- (I haven’t tracked that particular decision) Why not calling the module `HTTP`?

Yes, that has been discussed. A good way to get up to speed is flying over the archives:

  The swift-server-dev Archives

and the very few PRs. This group isn’t very active, it is a very reasonable amount of data to process :-)

Re-raising issues and providing out-of-context feedback months after is still valuable but a little hard to process :->

hh

···

On 22. Aug 2017, at 09:35, Adrian Zubarev via swift-server-dev <swift-server-dev@swift.org> wrote:

[Chris_Bailey]

Hi Georgios:

The protocol which the class needs to implement is 'HTTPRequestHandling'
but the class can have any name the user wants to use. I agree that for
the documentation (and the tests!) the use of 'Handler' is confusing and
could be better. How does the following look as a sample "Hello World"
app?

import HTTP

class MyServer: HTTPRequestHandling {
    func handle(request: HTTPRequest, response: HTTPResponseWriter ) ->
HTTPBodyProcessing {
        response.writeHeader(status: .ok)
        response.writeBody("Hello, World!")
        response.done()
        return .discardBody
    }
}

let server = HTTPServer()

try! server.start(port: 8080, handler: MyServer().handle)

Chris

···

From: Georgios Moschovitis <george.moschovitis@icloud.com>
To: Chris Bailey <BAILEYC@uk.ibm.com>
Cc: swift-server-dev@swift.org
Date: 03/09/2017 07:44
Subject: Re: [swift-server-dev] HTTP API Review

Had a (very) quick look, and in general it looks OK.
One thing that bothers me in the example is this ***Handler <->
***Handling inconsistency..

class SimpleHandler: HTTPRequestHandling

maybe something like

class WebApp: HTTPRequestHandling {
  ...
}

would make it less confusing?

-g.

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

[DevAndArtist (Adrian Meister)]

Well if it’s been settled in stone already, so be it. A short answer was enough for me, thanks :)

Hi Chris,

Well I do not participate in the server workgroup, but I do track its evolution from time to time.

...

- (I haven’t tracked that particular decision) Why not calling the module `HTTP`?

Yes, that has been discussed. A good way to get up to speed is flying over the archives:

https://lists.swift.org/pipermail/swift-server-dev/

and the very few PRs. This group isn’t very active, it is a very reasonable amount of data to process :-)

Re-raising issues and providing out-of-context feedback months after is still valuable but a little hard to process :->

hh

···

Am 22. August 2017 um 09:51:12, Helge Heß via swift-server-dev (swift-server-dev@swift.org) schrieb:
On 22. Aug 2017, at 09:35, Adrian Zubarev via swift-server-dev <swift-server-dev@swift.org> wrote:

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

[Alex_Blewitt]

I'm not convinced that using HTTPRequestHandling is a good protocol name. Why not use HTTPRequestHandler instead?

Alex

···

On 3 Sep 2017, at 18:51, Chris Bailey via swift-server-dev <swift-server-dev@swift.org> wrote:

Hi Georgios:

The protocol which the class needs to implement is 'HTTPRequestHandling' but the class can have any name the user wants to use. I agree that for the documentation (and the tests!) the use of 'Handler' is confusing and could be better. How does the following look as a sample "Hello World" app?

import HTTP

class MyServer: HTTPRequestHandling {
    func handle(request: HTTPRequest, response: HTTPResponseWriter ) -> HTTPBodyProcessing {
        response.writeHeader(status: .ok)
        response.writeBody("Hello, World!")
        response.done()
        return .discardBody
    }
}

let server = HTTPServer()

try! server.start(port: 8080, handler: MyServer().handle)

Chris

From: Georgios Moschovitis <george.moschovitis@icloud.com>
To: Chris Bailey <BAILEYC@uk.ibm.com>
Cc: swift-server-dev@swift.org
Date: 03/09/2017 07:44
Subject: Re: [swift-server-dev] HTTP API Review

Had a (very) quick look, and in general it looks OK.
One thing that bothers me in the example is this ***Handler <-> ***Handling inconsistency..

class SimpleHandler: HTTPRequestHandling

maybe something like

class WebApp: HTTPRequestHandling {
  ...
}

would make it less confusing?

-g.

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

[gmosx (Georgios Moschovitis)]

How does the following look as a sample "Hello World" app?

Looks much better to me. I would prefer the following though:

import HTTP

func handler(request: HTTPRequest, response: HTTPResponseWriter ) -> HTTPBodyProcessing {
    response.writeHeader(status: .ok)
    response.writeBody("Hello, World!")
    response.done()
    return .discardBody
}

try! HTTPServer().start(port: 8080, handler: handler)

···

import HTTP

class MyServer: HTTPRequestHandling {
    func handle(request: HTTPRequest, response: HTTPResponseWriter ) -> HTTPBodyProcessing {
        response.writeHeader(status: .ok)
        response.writeBody("Hello, World!")
        response.done()
        return .discardBody
    }
}

let server = HTTPServer()

try! server.start(port: 8080, handler: MyServer().handle)

Chris

From: Georgios Moschovitis <george.moschovitis@icloud.com>
To: Chris Bailey <BAILEYC@uk.ibm.com>
Cc: swift-server-dev@swift.org
Date: 03/09/2017 07:44
Subject: Re: [swift-server-dev] HTTP API Review

Had a (very) quick look, and in general it looks OK.
One thing that bothers me in the example is this ***Handler <-> ***Handling inconsistency..

class SimpleHandler: HTTPRequestHandling

maybe something like

class WebApp: HTTPRequestHandling {
  ...
}

would make it less confusing?

-g.

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

[gmosx (Georgios Moschovitis)]

Also,

- `HTTPBodyProcessing` is a very long word with no obvious meaning.
- I would use `HTTPResponse` instead of `HTTPResponseWriter`
- I would rename `writeBody` to `write` (and, maybe, `writeHeader` to `addHeader`, `setHeader`, `appendHeader` or something similar)

-g.

···

On 3 Sep 2017, at 8:51 PM, Chris Bailey <BAILEYC@uk.ibm.com> wrote:

Hi Georgios:

The protocol which the class needs to implement is 'HTTPRequestHandling' but the class can have any name the user wants to use. I agree that for the documentation (and the tests!) the use of 'Handler' is confusing and could be better. How does the following look as a sample "Hello World" app?

import HTTP

class MyServer: HTTPRequestHandling {
    func handle(request: HTTPRequest, response: HTTPResponseWriter ) -> HTTPBodyProcessing {
        response.writeHeader(status: .ok)
        response.writeBody("Hello, World!")
        response.done()
        return .discardBody
    }
}

let server = HTTPServer()

try! server.start(port: 8080, handler: MyServer().handle)

Chris

From: Georgios Moschovitis <george.moschovitis@icloud.com>
To: Chris Bailey <BAILEYC@uk.ibm.com>
Cc: swift-server-dev@swift.org
Date: 03/09/2017 07:44
Subject: Re: [swift-server-dev] HTTP API Review

Had a (very) quick look, and in general it looks OK.
One thing that bothers me in the example is this ***Handler <-> ***Handling inconsistency..

class SimpleHandler: HTTPRequestHandling

maybe something like

class WebApp: HTTPRequestHandling {
  ...
}

would make it less confusing?

-g.

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

[Helge_Hess1 (Helge Heß)]

I guess nothing is settled in _stone_ already, but I think it is good to read up on the pros and cons people raised about features/decisions before re-starting discussions from scratch :-)

hh

···

On 22. Aug 2017, at 09:53, Adrian Zubarev <adrian.zubarev@devandartist.com> wrote:

Well if it’s been settled in stone already, so be it. A short answer was enough for me, thanks :)

[mic (Michael Nisi)]

Why?

I prefer adjective protocol naming, because of its semantic meaning and it leaves the noun, HTTPRequestHandler in this case, free to be used by the implementation.

Michael

···

On 4. Sep 2017, at 10:28, Alex Blewitt via swift-server-dev <swift-server-dev@swift.org> wrote:

I'm not convinced that using HTTPRequestHandling is a good protocol name. Why not use HTTPRequestHandler instead?

Alex

[Chris_Bailey]

That does of course work as well - and may we'll be the preferred coding
style. We should definitely document both approaches.

Chris

···

From: Georgios Moschovitis <george.moschovitis@icloud.com>
To: Chris Bailey <BAILEYC@uk.ibm.com>
Cc: swift-server-dev@swift.org
Date: 04/09/2017 20:17
Subject: Re: [swift-server-dev] HTTP API Review

How does the following look as a sample "Hello World" app?

Looks much better to me. I would prefer the following though:

import HTTP

func handler(request: HTTPRequest, response: HTTPResponseWriter ) ->
HTTPBodyProcessing {
    response.writeHeader(status: .ok)
    response.writeBody("Hello, World!")
    response.done()
    return .discardBody
}

try! HTTPServer().start(port: 8080, handler: handler)

import HTTP

class MyServer: HTTPRequestHandling {
    func handle(request: HTTPRequest, response: HTTPResponseWriter ) ->
HTTPBodyProcessing {
        response.writeHeader(status: .ok)
        response.writeBody("Hello, World!")
        response.done()
        return .discardBody
    }
}

let server = HTTPServer()

try! server.start(port: 8080, handler: MyServer().handle)

Chris

From: Georgios Moschovitis <george.moschovitis@icloud.com>
To: Chris Bailey <BAILEYC@uk.ibm.com>
Cc: swift-server-dev@swift.org
Date: 03/09/2017 07:44
Subject: Re: [swift-server-dev] HTTP API Review

Had a (very) quick look, and in general it looks OK.
One thing that bothers me in the example is this ***Handler <->
***Handling inconsistency..

class SimpleHandler: HTTPRequestHandling

maybe something like

class WebApp: HTTPRequestHandling {
  ...
}

would make it less confusing?

-g.

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

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

[Chris_Bailey]

- `HTTPBodyProcessing` is a very long word with no obvious meaning.

Agreed, the naming here could be clearer as to what its purpose is. Do you
have any suggestions?

- I would use `HTTPResponse` instead of `HTTPResponseWriter`

The use of HTTPResponseWriter here is very deliberate because eventually
the API should be symmetrical for the server and client use cases, ie: a
server has access to a HTTPRequest and a HTTPResponseWriter, and a client
has access to a HTTPRequestWriter and a HTTPResponse.

- I would rename `writeBody` to `write` (and, maybe, `writeHeader` to

`addHeader`, `setHeader`, `appendHeader` or something similar)

I think if we we're to switch to using "write()" for writeBody(), then
we'd have to move to:
        func write(headers: HTTPHeaders, status: HTTPResponseStatus,
completion: @escaping (Result) -> Void)
        func write(body: UnsafeHTTPResponseBody, completion: @escaping
(Result) -> Void)
How does that look?

Chris

···

From: Georgios Moschovitis <george.moschovitis@icloud.com>
To: Chris Bailey <BAILEYC@uk.ibm.com>
Cc: swift-server-dev@swift.org
Date: 04/09/2017 20:26
Subject: Re: [swift-server-dev] HTTP API Review

Also,

- `HTTPBodyProcessing` is a very long word with no obvious meaning.
- I would use `HTTPResponse` instead of `HTTPResponseWriter`
- I would rename `writeBody` to `write` (and, maybe, `writeHeader` to
`addHeader`, `setHeader`, `appendHeader` or something similar)

-g.

On 3 Sep 2017, at 8:51 PM, Chris Bailey <BAILEYC@uk.ibm.com> wrote:

Hi Georgios:

The protocol which the class needs to implement is 'HTTPRequestHandling'
but the class can have any name the user wants to use. I agree that for
the documentation (and the tests!) the use of 'Handler' is confusing and
could be better. How does the following look as a sample "Hello World"
app?

import HTTP

class MyServer: HTTPRequestHandling {
    func handle(request: HTTPRequest, response: HTTPResponseWriter ) ->
HTTPBodyProcessing {
        response.writeHeader(status: .ok)
        response.writeBody("Hello, World!")
        response.done()
        return .discardBody
    }
}

let server = HTTPServer()

try! server.start(port: 8080, handler: MyServer().handle)

Chris

From: Georgios Moschovitis <george.moschovitis@icloud.com>
To: Chris Bailey <BAILEYC@uk.ibm.com>
Cc: swift-server-dev@swift.org
Date: 03/09/2017 07:44
Subject: Re: [swift-server-dev] HTTP API Review

Had a (very) quick look, and in general it looks OK.
One thing that bothers me in the example is this ***Handler <->
***Handling inconsistency..

class SimpleHandler: HTTPRequestHandling

maybe something like

class WebApp: HTTPRequestHandling {
  ...
}

would make it less confusing?

-g.

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

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

[Chris_Bailey]

Hi Adrian:

- (I haven’t tracked that particular decision) Why not calling the

module `HTTP`?

That's the eventual goal, although at the moment there's only support for
the "server" APIs. I think as we get closer to a complete set of APIs
we'll definitely rename. We can also do that sooner if it make sense.

- Even it the module is currently called `SwiftServerHTTP`, isn’t the

HTTP type prefix redundant?

   - If the Module was called `HTTP` then you could use `HTTP.Method`

if you wanted or simply omit the HTTP because it would be optional.

As Helge has said, we did have some previous discussion on this - the
quick summary is that retaining the HTTP prefix is beneficial for IDE
based code completion, so whilst its technically redundant it can actually
make it easier to program.

Various linking issues

These should just be fixed. If you'd like to raise PRs, those would be
gratefully received (although it might be work waiting until PR #26 is
merged first).

Thanks,

Chris

···

From: Helge Heß via swift-server-dev <swift-server-dev@swift.org>
To: Helge Heß via swift-server-dev <swift-server-dev@swift.org>
Date: 22/08/2017 08:58
Subject: Re: [swift-server-dev] HTTP API Review
Sent by: swift-server-dev-bounces@swift.org

On 22. Aug 2017, at 09:53, Adrian Zubarev <adrian.zubarev@devandartist.com> wrote:

Well if it’s been settled in stone already, so be it. A short answer was

enough for me, thanks :)

I guess nothing is settled in _stone_ already, but I think it is good to
read up on the pros and cons people raised about features/decisions before
re-starting discussions from scratch :-)

hh

_______________________________________________
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

[Alex_Blewitt]

Why?

Because in this instance, the protocol isn't meant to be used by the customer, it's intended to be implemented by the end customer. And the swift naming guidelines suggest that using an adjective for a protocol is for its capability.

The thing is, this protocol isn't doing anything. It's merely an API surface for others to implement, such that it can be plugged into an HTTP server implementation that knows how to talk to the API.

Separately, having '-ing' describe the protocol and '-er' be an implementation of that protocol sounds like a recipe for confusion later on.

Alex

···

On 4 Sep 2017, at 13:13, Michael Nisi <michael.nisi@gmail.com> wrote:

I prefer adjective protocol naming, because of its semantic meaning and it leaves the noun, HTTPRequestHandler in this case, free to be used by the implementation.

Michael

On 4. Sep 2017, at 10:28, Alex Blewitt via swift-server-dev <swift-server-dev@swift.org> wrote:

I'm not convinced that using HTTPRequestHandling is a good protocol name. Why not use HTTPRequestHandler instead?

Alex

[gmosx (Georgios Moschovitis)]

>> - `HTTPBodyProcessing` is a very long word with no obvious meaning.

Agreed, the naming here could be clearer as to what its purpose is. Do you have any suggestions?

Unfortunately, no :(

>> - I would use `HTTPResponse` instead of `HTTPResponseWriter`

The use of HTTPResponseWriter here is very deliberate because eventually the API should be symmetrical for the server and client use cases, ie: a server has access to a HTTPRequest and a HTTPResponseWriter, and a client has access to a HTTPRequestWriter and a HTTPResponse.

Hm, that makes sense.

>> - I would rename `writeBody` to `write` (and, maybe, `writeHeader` to `addHeader`, `setHeader`, `appendHeader` or something similar)

I think if we we're to switch to using "write()" for writeBody(), then we'd have to move to:
        func write(headers: HTTPHeaders, status: HTTPResponseStatus, completion: @escaping (Result) -> Void)
        func write(body: UnsafeHTTPResponseBody, completion: @escaping (Result) -> Void)
How does that look?

Ah, that looks even more Swifty, I like it :-)

-g.

[Chris_Bailey]

Thanks for the feedback Georgios.

I'll raise a PR for the change of writeHeader()/writeBody() to write() and
see if there's any objections.

Chris

···

From: Georgios Moschovitis <george.moschovitis@icloud.com>
To: Chris Bailey <BAILEYC@uk.ibm.com>
Cc: swift-server-dev@swift.org
Date: 09/09/2017 09:17
Subject: Re: [swift-server-dev] HTTP API Review

- `HTTPBodyProcessing` is a very long word with no obvious meaning.

Agreed, the naming here could be clearer as to what its purpose is. Do you
have any suggestions?

Unfortunately, no :(

- I would use `HTTPResponse` instead of `HTTPResponseWriter`

The use of HTTPResponseWriter here is very deliberate because eventually
the API should be symmetrical for the server and client use cases, ie: a
server has access to a HTTPRequest and a HTTPResponseWriter, and a client
has access to a HTTPRequestWriter and a HTTPResponse.

Hm, that makes sense.

- I would rename `writeBody` to `write` (and, maybe, `writeHeader` to

`addHeader`, `setHeader`, `appendHeader` or something similar)

I think if we we're to switch to using "write()" for writeBody(), then
we'd have to move to:
        func write(headers: HTTPHeaders, status: HTTPResponseStatus,
completion: @escaping (Result) -> Void)
        func write(body: UnsafeHTTPResponseBody, completion: @escaping
(Result) -> Void)
How does that look?

Ah, that looks even more Swifty, I like it :-)

-g.

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

[Chris_Bailey]

Hi Georgios:

I've raised the following PR to carry this discussion forwards:
        Convert writeXXXX() calls to write(xxxx:) by seabaylea · Pull Request #45 · swift-server/http · GitHub

The area that's worth discussing is the conversion of
        write(headers:status)
into write(status:)

The write(status:) call is a convenience wrapper for writing headers, so
a side effect is that it may not be obvious that it results in the writing
of the headers to the socket - i.e. a subsequent call to write(headers:)
isn't possible.

Chris

···

From: Chris Bailey/UK/IBM
To: Georgios Moschovitis <george.moschovitis@icloud.com>
Cc: swift-server-dev@swift.org
Date: 10/09/2017 16:09
Subject: Re: [swift-server-dev] HTTP API Review

Thanks for the feedback Georgios.

I'll raise a PR for the change of writeHeader()/writeBody() to write() and
see if there's any objections.

Chris

From: Georgios Moschovitis <george.moschovitis@icloud.com>
To: Chris Bailey <BAILEYC@uk.ibm.com>
Cc: swift-server-dev@swift.org
Date: 09/09/2017 09:17
Subject: Re: [swift-server-dev] HTTP API Review

- `HTTPBodyProcessing` is a very long word with no obvious meaning.

Agreed, the naming here could be clearer as to what its purpose is. Do you
have any suggestions?

Unfortunately, no :(

- I would use `HTTPResponse` instead of `HTTPResponseWriter`

The use of HTTPResponseWriter here is very deliberate because eventually
the API should be symmetrical for the server and client use cases, ie: a
server has access to a HTTPRequest and a HTTPResponseWriter, and a client
has access to a HTTPRequestWriter and a HTTPResponse.

Hm, that makes sense.

- I would rename `writeBody` to `write` (and, maybe, `writeHeader` to

`addHeader`, `setHeader`, `appendHeader` or something similar)

I think if we we're to switch to using "write()" for writeBody(), then
we'd have to move to:
        func write(headers: HTTPHeaders, status: HTTPResponseStatus,
completion: @escaping (Result) -> Void)
        func write(body: UnsafeHTTPResponseBody, completion: @escaping
(Result) -> Void)
How does that look?

Ah, that looks even more Swifty, I like it :-)

-g.

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

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