Let me summarize what we discuss in the previous emails.

We agree on
a) have the following API in HttpServletRequest:
Map<String, String> getTrailerFields()
b) there is no validation of trailer fields.

The following is from javadoc of (a)
* @return A map of trailer fields in which all the keys are in lowercase,
* regardless of the case they had at the protocol level, or the empty map
* if there is no trailer or the underlying transport does not support trailer.

MM has raised some questions on the behavior of the API in (a) under the following condition:
1) request is not chunked, like content-length = 0,
from the above javadoc, it will return a empty map
2) request is chunked, but no trailers are received.
3) request is chunked, the complete set of trailer fields have not yet arrived

(2) and (3) will happens even when the application has read all the data.

As MM (and MT) has suggested that we may like to add an API to check whether trailer fields
are available to read. So we may like to add an API in HttpServletRequest as follows:
boolean isTrailerFieldsAvailable();
(Or boolean isTrailerAvailable(); )

And calling getTrailerFields() before isTrailerFieldsAvailable() == false will throw an IllegalStateException

In particular, we have:
For conditions (2) and (3), isTrailerFieldsAvailable() == true when the application has read all the request
data and trailer fields are available.
If getTrailerFields() are invoked when isTrailerFieldsAvailable() == false, then it is an IllegalStateException.

For condition (1), isTrailerFieldsAvailable() == false all the time

Please let me know if you have any comment.
Shing Wai Chan

Hi, EG members,
Any comments on below?
Thanks.
Shing Wai Chan

On Fri, May 19, 2017 at 6:06 AM, Shing Wai Chan
<shing.wai.chan@...> wrote:

Here is the javadoc for the proposed #isTrailerFieldsAvailable() API:
/**
* Return a boolean indicating whether trailer fields are available.
*
* This method returns true if and only if all the following conditions
are
* satisfied:
* <ol type="a">
* <li> the request is using chunked transfer encoding

What about if HTTP/2 is in use?

Personally I think we should just drop this line, and just leave the
following two lines (although I don't feel super strongly about it
either way). With HTTP/2 trailers can always be sent so as HTTP/2
gains adoption this distinction will be meaningless, and if for some
reason the app wants to know if the request used chunking they can
just check the request headers.

Stuart

* <li> the application has read all the request data and an EOF
* indication has been returned from the {@link #getReader}
* or {@link #getInputStream}
* <li> all the trailer fields sent by the client have been received.
* Note that it is possible that the client has sent no trailer
fields.
* </ol>
*
* @implSpec
* The default implementation returns false.
*
* @return a boolean whether trailer fields are available
*
* @since Servlet 4.0
*/
default public boolean isTrailerFieldsAvailable() {
return false;
}

For your convenience, I also include the corresponding updated javadoc for
#getTrailerFields() API:
/**
* Get the request trailer fields.
*
* <p>The returned map is not backed by the {@code HttpServletRequest}
object,
* so changes in the returned map are not reflected in the
* {@code HttpServletRequest} object, and vice-versa.</p>
*
* <p>{@link #isTrailerFieldsAvailable()} should be called first to
determine
* if it is safe to call this method without causing an exception.</p>
*
* @implSpec
* The default implementation throws IllegalStateException.
*
* @return A map of trailer fields in which all the keys are in
lowercase,
* regardless of the case they had at the protocol level. If there are
no
* trailer fields, yet {@link #isTrailerFieldsAvailable} is returning
true,
* the empty map is returned.
*
* @throws IllegalStateException if {@link #isTrailerFieldsAvailable()}
is false
*
* @since Servlet 4.0
*/
default public Map<String, String> getTrailerFields() {
throw new IllegalStateException();
}

Please let me know your comment by COB tomorrow, May 19.
Thanks.
Shing Wai Chan


On May 17, 2017, at 3:37 PM, Shing Wai Chan <shing.wai.chan@...>
wrote:

SW> As MM (and MT) has suggested that we may like to add an API to check
SW> whether trailer fields are available to read. So we may like to add
SW> an API in HttpServletRequest as follows:
SW> boolean isTrailerFieldsAvailable();
SW> (Or boolean isTrailerAvailable(); )

SW> And calling getTrailerFields() before isTrailerFieldsAvailable() ==
false
SW> will throw an IllegalStateException

And isTrailerFieldsAvailable() == true if and only if
a) the request is chunked
b) the application has read all the request data
b) the trailer fields have been received

Please let me know if you have any comment.
Shing Wai Chan

----- Original Message -----
From: shing.wai.chan@...
To: servlet-spec@javaee.groups.io
Sent: Monday, May 15, 2017 2:17:58 PM GMT -08:00 US/Canada Pacific
Subject: Re: [servlet-spec] read trailer

On April 21, 2017, we agree to choose NeverReturnNull option.
In this case,
Map<String, String> getTrailerFields()
will never return null.
(In general, we do not return null for API with Collection return type.)

In this case, we will need to have #isTrailerFieldsAvailable().
Thanks.

Shing Wai Chan


On May 15, 2017, at 12:09 PM, Greg Wilkins <gregw@...> wrote:


On 15 May 2017 at 20:12, Shing Wai Chan <shing.wai.chan@...> wrote:

isTrailerFieldsAvailable

I don't think isTrailerFieldsAvailable is necessary.

An application has to wait until -1 is read (or a 0 length request) before
calling any API else it will get an ISE. Then once it has waited, we can
signal no trailers possibe with a null return and no trailers sent with a
empty map.

If we had the isTrailerFieldsAvailable, then in Jetty it would simply be
implemented as:

boolean isTrailerFieldsAvailable()
{
return this.trailers!=null;
}


--
Greg Wilkins <gregw@...> CTO http://webtide.com

On May 18, 2017, at 1:32 PM, Stuart Douglas <sdouglas@...> wrote:

On Fri, May 19, 2017 at 6:06 AM, Shing Wai Chan
<shing.wai.chan@...> wrote:

Here is the javadoc for the proposed #isTrailerFieldsAvailable() API:
/**
* Return a boolean indicating whether trailer fields are available.
*
* This method returns true if and only if all the following conditions
are
* satisfied:
* <ol type="a">
* <li> the request is using chunked transfer encoding

What about if HTTP/2 is in use?

Personally I think we should just drop this line, and just leave the
following two lines (although I don't feel super strongly about it
either way). With HTTP/2 trailers can always be sent so as HTTP/2
gains adoption this distinction will be meaningless, and if for some
reason the app wants to know if the request used chunking they can
just check the request headers.

Can we send HTTP2/trailer when it is not chunked transfer encoding?
I think we cannot.

In section 8.1 of RFC 7540:
4. optionally, one HEADERS frame, followed by zero or more
CONTINUATION frames containing the trailer-part, if present (see
[RFC7230], Section 4.1.2).

In section 4.1.2 of RFC 7230:
A trailer allows the sender to include additional fields at the end
of a chunked message in order to supply metadata that might be
dynamically generated while the message body is sent, such as a
message integrity check, digital signature, or post-processing
status.

In Appendix B. Collected ABNF of RFC 7230, trailer-part is only used in chunked-body.

If we drop the first condition, then we are allowing something more general than HTTP2?
I think we should keep the first condition in this case.
Thanks.
Shing Wai Chan

Stuart

* <li> the application has read all the request data and an EOF
* indication has been returned from the {@link #getReader}
* or {@link #getInputStream}
* <li> all the trailer fields sent by the client have been received.
* Note that it is possible that the client has sent no trailer
fields.
* </ol>
*
* @implSpec
* The default implementation returns false.
*
* @return a boolean whether trailer fields are available
*
* @since Servlet 4.0
*/
default public boolean isTrailerFieldsAvailable() {
return false;
}

For your convenience, I also include the corresponding updated javadoc for
#getTrailerFields() API:
/**
* Get the request trailer fields.
*
* <p>The returned map is not backed by the {@code HttpServletRequest}
object,
* so changes in the returned map are not reflected in the
* {@code HttpServletRequest} object, and vice-versa.</p>
*
* <p>{@link #isTrailerFieldsAvailable()} should be called first to
determine
* if it is safe to call this method without causing an exception.</p>
*
* @implSpec
* The default implementation throws IllegalStateException.
*
* @return A map of trailer fields in which all the keys are in
lowercase,
* regardless of the case they had at the protocol level. If there are
no
* trailer fields, yet {@link #isTrailerFieldsAvailable} is returning
true,
* the empty map is returned.
*
* @throws IllegalStateException if {@link #isTrailerFieldsAvailable()}
is false
*
* @since Servlet 4.0
*/
default public Map<String, String> getTrailerFields() {
throw new IllegalStateException();
}

Please let me know your comment by COB tomorrow, May 19.
Thanks.
Shing Wai Chan


On May 17, 2017, at 3:37 PM, Shing Wai Chan <shing.wai.chan@...>
wrote:

SW> As MM (and MT) has suggested that we may like to add an API to check
SW> whether trailer fields are available to read. So we may like to add
SW> an API in HttpServletRequest as follows:
SW> boolean isTrailerFieldsAvailable();
SW> (Or boolean isTrailerAvailable(); )

SW> And calling getTrailerFields() before isTrailerFieldsAvailable() ==
false
SW> will throw an IllegalStateException

And isTrailerFieldsAvailable() == true if and only if
a) the request is chunked
b) the application has read all the request data
b) the trailer fields have been received

Please let me know if you have any comment.
Shing Wai Chan

----- Original Message -----
From: shing.wai.chan@...
To: servlet-spec@javaee.groups.io
Sent: Monday, May 15, 2017 2:17:58 PM GMT -08:00 US/Canada Pacific
Subject: Re: [servlet-spec] read trailer

On April 21, 2017, we agree to choose NeverReturnNull option.
In this case,
Map<String, String> getTrailerFields()
will never return null.
(In general, we do not return null for API with Collection return type.)

In this case, we will need to have #isTrailerFieldsAvailable().
Thanks.

Shing Wai Chan


On May 15, 2017, at 12:09 PM, Greg Wilkins <gregw@...> wrote:


On 15 May 2017 at 20:12, Shing Wai Chan <shing.wai.chan@...> wrote:

isTrailerFieldsAvailable

I don't think isTrailerFieldsAvailable is necessary.

An application has to wait until -1 is read (or a 0 length request) before
calling any API else it will get an ISE. Then once it has waited, we can
signal no trailers possibe with a null return and no trailers sent with a
empty map.

If we had the isTrailerFieldsAvailable, then in Jetty it would simply be
implemented as:

boolean isTrailerFieldsAvailable()
{
return this.trailers!=null;
}


--
Greg Wilkins <gregw@...> CTO http://webtide.com

On Fri, May 19, 2017 at 7:05 AM, Shing Wai Chan
<shing.wai.chan@...> wrote:

On May 18, 2017, at 1:32 PM, Stuart Douglas <sdouglas@...> wrote:

On Fri, May 19, 2017 at 6:06 AM, Shing Wai Chan
<shing.wai.chan@...> wrote:

Here is the javadoc for the proposed #isTrailerFieldsAvailable() API:
/**
* Return a boolean indicating whether trailer fields are available.
*
* This method returns true if and only if all the following conditions
are
* satisfied:
* <ol type="a">
* <li> the request is using chunked transfer encoding

What about if HTTP/2 is in use?

Personally I think we should just drop this line, and just leave the
following two lines (although I don't feel super strongly about it
either way). With HTTP/2 trailers can always be sent so as HTTP/2
gains adoption this distinction will be meaningless, and if for some
reason the app wants to know if the request used chunking they can
just check the request headers.

Can we send HTTP2/trailer when it is not chunked transfer encoding?
I think we cannot.

In section 8.1 of RFC 7540:
4. optionally, one HEADERS frame, followed by zero or more
CONTINUATION frames containing the trailer-part, if present (see
[RFC7230], Section 4.1.2).

HTTP/2 will never use chunked encoding. (8.1: HTTP/2 uses DATA frames
to carry message payloads. The "chunked" transfer encoding defined in
Section 4.1 of [RFC7230] MUST NOT be used in HTTP/2.).

But HTTP/2 does support trailers. Even though RFC 7230 explicitly
mentions chunking and RFC 7540 references this I believe RFC7230 is
referenced in relation to explaining the sematics of trailers, not the
chunked limitation (otherwise HTTP/2 would not reference trailers at
all, as chunking is prohibited).

In section 4.1.2 of RFC 7230:
A trailer allows the sender to include additional fields at the end
of a chunked message in order to supply metadata that might be
dynamically generated while the message body is sent, such as a
message integrity check, digital signature, or post-processing
status.

In Appendix B. Collected ABNF of RFC 7230, trailer-part is only used in chunked-body.

If we drop the first condition, then we are allowing something more general than HTTP2?

Yes, which is a good thing. We should really only care about
semantics, not the underlying transport technology. e.g. lots of
containers support AJP, which for the most part matches HTTP
semantics. If we start specifying everything in terms of specifics of
a given version of the HTTP protocol then support for this sort of
thing could become harder.

Stuart

I think we should keep the first condition in this case.
Thanks.
Shing Wai Chan

Stuart

* <li> the application has read all the request data and an EOF
* indication has been returned from the {@link #getReader}
* or {@link #getInputStream}
* <li> all the trailer fields sent by the client have been received.
* Note that it is possible that the client has sent no trailer
fields.
* </ol>
*
* @implSpec
* The default implementation returns false.
*
* @return a boolean whether trailer fields are available
*
* @since Servlet 4.0
*/
default public boolean isTrailerFieldsAvailable() {
return false;
}

For your convenience, I also include the corresponding updated javadoc for
#getTrailerFields() API:
/**
* Get the request trailer fields.
*
* <p>The returned map is not backed by the {@code HttpServletRequest}
object,
* so changes in the returned map are not reflected in the
* {@code HttpServletRequest} object, and vice-versa.</p>
*
* <p>{@link #isTrailerFieldsAvailable()} should be called first to
determine
* if it is safe to call this method without causing an exception.</p>
*
* @implSpec
* The default implementation throws IllegalStateException.
*
* @return A map of trailer fields in which all the keys are in
lowercase,
* regardless of the case they had at the protocol level. If there are
no
* trailer fields, yet {@link #isTrailerFieldsAvailable} is returning
true,
* the empty map is returned.
*
* @throws IllegalStateException if {@link #isTrailerFieldsAvailable()}
is false
*
* @since Servlet 4.0
*/
default public Map<String, String> getTrailerFields() {
throw new IllegalStateException();
}

Please let me know your comment by COB tomorrow, May 19.
Thanks.
Shing Wai Chan


On May 17, 2017, at 3:37 PM, Shing Wai Chan <shing.wai.chan@...>
wrote:

SW> As MM (and MT) has suggested that we may like to add an API to check
SW> whether trailer fields are available to read. So we may like to add
SW> an API in HttpServletRequest as follows:
SW> boolean isTrailerFieldsAvailable();
SW> (Or boolean isTrailerAvailable(); )

SW> And calling getTrailerFields() before isTrailerFieldsAvailable() ==
false
SW> will throw an IllegalStateException

And isTrailerFieldsAvailable() == true if and only if
a) the request is chunked
b) the application has read all the request data
b) the trailer fields have been received

Please let me know if you have any comment.
Shing Wai Chan

----- Original Message -----
From: shing.wai.chan@...
To: servlet-spec@javaee.groups.io
Sent: Monday, May 15, 2017 2:17:58 PM GMT -08:00 US/Canada Pacific
Subject: Re: [servlet-spec] read trailer

On April 21, 2017, we agree to choose NeverReturnNull option.
In this case,
Map<String, String> getTrailerFields()
will never return null.
(In general, we do not return null for API with Collection return type.)

In this case, we will need to have #isTrailerFieldsAvailable().
Thanks.

Shing Wai Chan


On May 15, 2017, at 12:09 PM, Greg Wilkins <gregw@...> wrote:


On 15 May 2017 at 20:12, Shing Wai Chan <shing.wai.chan@...> wrote:

isTrailerFieldsAvailable

I don't think isTrailerFieldsAvailable is necessary.

An application has to wait until -1 is read (or a 0 length request) before
calling any API else it will get an ISE. Then once it has waited, we can
signal no trailers possibe with a null return and no trailers sent with a
empty map.

If we had the isTrailerFieldsAvailable, then in Jetty it would simply be
implemented as:

boolean isTrailerFieldsAvailable()
{
return this.trailers!=null;
}


--
Greg Wilkins <gregw@...> CTO http://webtide.com

On 22/05/17 06:52, Greg Wilkins wrote:

I think we need to say that the application had read to EOF or that
there is no content. It would be a bit silly to force an app to read to
EOF if content length is known to be 0

I'd also add "or if the container knows that the underlying protocol
does not support trailers".

This would then meet the original use case I had in mind.

Mark

Cheers

On 19 May 2017 00:09, "Shing Wai Chan" <shing.wai.chan@...
<mailto:shing.wai.chan@...>> wrote:

Ok. I agree that we should drop the chunked encoding condition in my
previous proposal.
In this case, I will revise the javadoc of #isTrailerFieldsAvailable
as follows:

* This method returns true if and only if both of the following
conditions are
* satisfied:
* <ol type="a">
* <li> the application has read all the request data and an EOF
* indication has been returned from the {@link #getReader}
* or {@link #getInputStream}
* <li> all the trailer fields sent by the client have been
received.
* Note that it is possible that the client has sent no
trailer fields.
* </ol>

Thanks.
Shing Wai Chan

On May 18, 2017, at 2:17 PM, Stuart Douglas <sdouglas@...
<mailto:sdouglas@...>> wrote:

On Fri, May 19, 2017 at 7:05 AM, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>> wrote:

On May 18, 2017, at 1:32 PM, Stuart Douglas <sdouglas@...
<mailto:sdouglas@...>> wrote:

On Fri, May 19, 2017 at 6:06 AM, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>>
wrote:

Here is the javadoc for the proposed
#isTrailerFieldsAvailable() API:
/**
* Return a boolean indicating whether trailer fields are
available.
*
* This method returns true if and only if all the following
conditions
are
* satisfied:
* <ol type="a">
* <li> the request is using chunked transfer encoding

What about if HTTP/2 is in use?

Personally I think we should just drop this line, and just leave the
following two lines (although I don't feel super strongly about it
either way). With HTTP/2 trailers can always be sent so as HTTP/2
gains adoption this distinction will be meaningless, and if for some
reason the app wants to know if the request used chunking they can
just check the request headers.

Can we send HTTP2/trailer when it is not chunked transfer encoding?
I think we cannot.

In section 8.1 of RFC 7540:
4. optionally, one HEADERS frame, followed by zero or more
CONTINUATION frames containing the trailer-part, if
present (see
[RFC7230], Section 4.1.2).

HTTP/2 will never use chunked encoding. (8.1: HTTP/2 uses DATA frames
to carry message payloads. The "chunked" transfer encoding defined in
Section 4.1 of [RFC7230] MUST NOT be used in HTTP/2.).

But HTTP/2 does support trailers. Even though RFC 7230 explicitly
mentions chunking and RFC 7540 references this I believe RFC7230 is
referenced in relation to explaining the sematics of trailers, not the
chunked limitation (otherwise HTTP/2 would not reference trailers at
all, as chunking is prohibited).

In section 4.1.2 of RFC 7230:
A trailer allows the sender to include additional fields
at the end
of a chunked message in order to supply metadata that might be
dynamically generated while the message body is sent, such
as a
message integrity check, digital signature, or post-processing
status.

In Appendix B. Collected ABNF of RFC 7230, trailer-part is only
used in chunked-body.

If we drop the first condition, then we are allowing something
more general than HTTP2?

Yes, which is a good thing. We should really only care about
semantics, not the underlying transport technology. e.g. lots of
containers support AJP, which for the most part matches HTTP
semantics. If we start specifying everything in terms of specifics of
a given version of the HTTP protocol then support for this sort of
thing could become harder.

Stuart

I think we should keep the first condition in this case.
Thanks.
Shing Wai Chan

Stuart

* <li> the application has read all the request data and
an EOF
* indication has been returned from the {@link
#getReader}
* or {@link #getInputStream}
* <li> all the trailer fields sent by the client have been
received.
* Note that it is possible that the client has sent
no trailer
fields.
* </ol>
*
* @implSpec
* The default implementation returns false.
*
* @return a boolean whether trailer fields are available
*
* @since Servlet 4.0
*/
default public boolean isTrailerFieldsAvailable() {
return false;
}

For your convenience, I also include the corresponding updated
javadoc for
#getTrailerFields() API:
/**
* Get the request trailer fields.
*
* <p>The returned map is not backed by the {@code
HttpServletRequest}
object,
* so changes in the returned map are not reflected in the
* {@code HttpServletRequest} object, and vice-versa.</p>
*
* <p>{@link #isTrailerFieldsAvailable()} should be called
first to
determine
* if it is safe to call this method without causing an
exception.</p>
*
* @implSpec
* The default implementation throws IllegalStateException.
*
* @return A map of trailer fields in which all the keys are in
lowercase,
* regardless of the case they had at the protocol level. If
there are
no
* trailer fields, yet {@link #isTrailerFieldsAvailable} is
returning
true,
* the empty map is returned.
*
* @throws IllegalStateException if {@link
#isTrailerFieldsAvailable()}
is false
*
* @since Servlet 4.0
*/
default public Map<String, String> getTrailerFields() {
throw new IllegalStateException();
}

Please let me know your comment by COB tomorrow, May 19.
Thanks.
Shing Wai Chan


On May 17, 2017, at 3:37 PM, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>>
wrote:

SW> As MM (and MT) has suggested that we may like to add an API
to check
SW> whether trailer fields are available to read. So we may
like to add
SW> an API in HttpServletRequest as follows:
SW> boolean isTrailerFieldsAvailable();
SW> (Or boolean isTrailerAvailable(); )

SW> And calling getTrailerFields() before
isTrailerFieldsAvailable() ==
false
SW> will throw an IllegalStateException

And isTrailerFieldsAvailable() == true if and only if
a) the request is chunked
b) the application has read all the request data
b) the trailer fields have been received

Please let me know if you have any comment.
Shing Wai Chan

----- Original Message -----
From: shing.wai.chan@... <mailto:shing.wai.chan@...>
To: servlet-spec@javaee.groups.io
<mailto:servlet-spec@javaee.groups.io>
Sent: Monday, May 15, 2017 2:17:58 PM GMT -08:00 US/Canada Pacific
Subject: Re: [servlet-spec] read trailer

On April 21, 2017, we agree to choose NeverReturnNull option.
In this case,
Map<String, String> getTrailerFields()
will never return null.
(In general, we do not return null for API with Collection
return type.)

In this case, we will need to have #isTrailerFieldsAvailable().
Thanks.

Shing Wai Chan


On May 15, 2017, at 12:09 PM, Greg Wilkins <gregw@...
<mailto:gregw@...>> wrote:


On 15 May 2017 at 20:12, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>>
wrote:

isTrailerFieldsAvailable

I don't think isTrailerFieldsAvailable is necessary.

An application has to wait until -1 is read (or a 0 length
request) before
calling any API else it will get an ISE. Then once it has
waited, we can
signal no trailers possibe with a null return and no trailers
sent with a
empty map.

If we had the isTrailerFieldsAvailable, then in Jetty it would
simply be
implemented as:

boolean isTrailerFieldsAvailable()
{
return this.trailers!=null;
}


--
Greg Wilkins <gregw@... <mailto:gregw@...>> CTO
http://webtide.com

On May 22, 2017, at 4:09 AM, Mark Thomas <markt@...> wrote:

On 22/05/17 06:52, Greg Wilkins wrote:

I think we need to say that the application had read to EOF or that
there is no content. It would be a bit silly to force an app to read to
EOF if content length is known to be 0

I'd also add "or if the container knows that the underlying protocol
does not support trailers”.

+1.

To avoid the confusion, per discussion with Ed, I would rename the API as #isTrailerFieldsReady().
The API and the javadoc are as follows:

/**
* Return a boolean indicating whether trailer fields are ready to read
* using {@link #getTrailerFields}.
*
* This method returns true if and only if all of the following conditions
* are satisfied:
* <ol type="a">
* <li> the underlying protocol supports trailer fields. HTTP versions
* less than 1.1 do not support trailer fields.
* <li> the application has read all the request data and an EOF
* indication has been returned from the {@link #getReader}
* or {@link #getInputStream}, or the content length is zero,
* <li> all the trailer fields sent by the client have been received.
* Note that it is possible that the client has sent no trailer fields.
* </ol>
*
* @implSpec
* The default implementation returns false.
*
* @return a boolean whether trailer fields are ready to read
*
* @since Servlet 4.0
*/
default public boolean isTrailerFieldsReady() {
return false;
}

Thanks.
Shing Wai Chan

This would then meet the original use case I had in mind.

Mark

Cheers

On 19 May 2017 00:09, "Shing Wai Chan" <shing.wai.chan@...
<mailto:shing.wai.chan@...>> wrote:

Ok. I agree that we should drop the chunked encoding condition in my
previous proposal.
In this case, I will revise the javadoc of #isTrailerFieldsAvailable
as follows:

* This method returns true if and only if both of the following
conditions are
* satisfied:
* <ol type="a">
* <li> the application has read all the request data and an EOF
* indication has been returned from the {@link #getReader}
* or {@link #getInputStream}
* <li> all the trailer fields sent by the client have been
received.
* Note that it is possible that the client has sent no
trailer fields.
* </ol>

Thanks.
Shing Wai Chan

On May 18, 2017, at 2:17 PM, Stuart Douglas <sdouglas@...
<mailto:sdouglas@...>> wrote:

On Fri, May 19, 2017 at 7:05 AM, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>> wrote:

On May 18, 2017, at 1:32 PM, Stuart Douglas <sdouglas@...
<mailto:sdouglas@...>> wrote:

On Fri, May 19, 2017 at 6:06 AM, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>>
wrote:

Here is the javadoc for the proposed
#isTrailerFieldsAvailable() API:
/**
* Return a boolean indicating whether trailer fields are
available.
*
* This method returns true if and only if all the following
conditions
are
* satisfied:
* <ol type="a">
* <li> the request is using chunked transfer encoding

What about if HTTP/2 is in use?

Personally I think we should just drop this line, and just leave the
following two lines (although I don't feel super strongly about it
either way). With HTTP/2 trailers can always be sent so as HTTP/2
gains adoption this distinction will be meaningless, and if for some
reason the app wants to know if the request used chunking they can
just check the request headers.

Can we send HTTP2/trailer when it is not chunked transfer encoding?
I think we cannot.

In section 8.1 of RFC 7540:
4. optionally, one HEADERS frame, followed by zero or more
CONTINUATION frames containing the trailer-part, if
present (see
[RFC7230], Section 4.1.2).

HTTP/2 will never use chunked encoding. (8.1: HTTP/2 uses DATA frames
to carry message payloads. The "chunked" transfer encoding defined in
Section 4.1 of [RFC7230] MUST NOT be used in HTTP/2.).

But HTTP/2 does support trailers. Even though RFC 7230 explicitly
mentions chunking and RFC 7540 references this I believe RFC7230 is
referenced in relation to explaining the sematics of trailers, not the
chunked limitation (otherwise HTTP/2 would not reference trailers at
all, as chunking is prohibited).

In section 4.1.2 of RFC 7230:
A trailer allows the sender to include additional fields
at the end
of a chunked message in order to supply metadata that might be
dynamically generated while the message body is sent, such
as a
message integrity check, digital signature, or post-processing
status.

In Appendix B. Collected ABNF of RFC 7230, trailer-part is only
used in chunked-body.

If we drop the first condition, then we are allowing something
more general than HTTP2?

Yes, which is a good thing. We should really only care about
semantics, not the underlying transport technology. e.g. lots of
containers support AJP, which for the most part matches HTTP
semantics. If we start specifying everything in terms of specifics of
a given version of the HTTP protocol then support for this sort of
thing could become harder.

Stuart

I think we should keep the first condition in this case.
Thanks.
Shing Wai Chan

Stuart

* <li> the application has read all the request data and
an EOF
* indication has been returned from the {@link
#getReader}
* or {@link #getInputStream}
* <li> all the trailer fields sent by the client have been
received.
* Note that it is possible that the client has sent
no trailer
fields.
* </ol>
*
* @implSpec
* The default implementation returns false.
*
* @return a boolean whether trailer fields are available
*
* @since Servlet 4.0
*/
default public boolean isTrailerFieldsAvailable() {
return false;
}

For your convenience, I also include the corresponding updated
javadoc for
#getTrailerFields() API:
/**
* Get the request trailer fields.
*
* <p>The returned map is not backed by the {@code
HttpServletRequest}
object,
* so changes in the returned map are not reflected in the
* {@code HttpServletRequest} object, and vice-versa.</p>
*
* <p>{@link #isTrailerFieldsAvailable()} should be called
first to
determine
* if it is safe to call this method without causing an
exception.</p>
*
* @implSpec
* The default implementation throws IllegalStateException.
*
* @return A map of trailer fields in which all the keys are in
lowercase,
* regardless of the case they had at the protocol level. If
there are
no
* trailer fields, yet {@link #isTrailerFieldsAvailable} is
returning
true,
* the empty map is returned.
*
* @throws IllegalStateException if {@link
#isTrailerFieldsAvailable()}
is false
*
* @since Servlet 4.0
*/
default public Map<String, String> getTrailerFields() {
throw new IllegalStateException();
}

Please let me know your comment by COB tomorrow, May 19.
Thanks.
Shing Wai Chan


On May 17, 2017, at 3:37 PM, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>>
wrote:

SW> As MM (and MT) has suggested that we may like to add an API
to check
SW> whether trailer fields are available to read. So we may
like to add
SW> an API in HttpServletRequest as follows:
SW> boolean isTrailerFieldsAvailable();
SW> (Or boolean isTrailerAvailable(); )

SW> And calling getTrailerFields() before
isTrailerFieldsAvailable() ==
false
SW> will throw an IllegalStateException

And isTrailerFieldsAvailable() == true if and only if
a) the request is chunked
b) the application has read all the request data
b) the trailer fields have been received

Please let me know if you have any comment.
Shing Wai Chan

----- Original Message -----
From: shing.wai.chan@... <mailto:shing.wai.chan@...>
To: servlet-spec@javaee.groups.io
<mailto:servlet-spec@javaee.groups.io>
Sent: Monday, May 15, 2017 2:17:58 PM GMT -08:00 US/Canada Pacific
Subject: Re: [servlet-spec] read trailer

On April 21, 2017, we agree to choose NeverReturnNull option.
In this case,
Map<String, String> getTrailerFields()
will never return null.
(In general, we do not return null for API with Collection
return type.)

In this case, we will need to have #isTrailerFieldsAvailable().
Thanks.

Shing Wai Chan


On May 15, 2017, at 12:09 PM, Greg Wilkins <gregw@...
<mailto:gregw@...>> wrote:


On 15 May 2017 at 20:12, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>>
wrote:

isTrailerFieldsAvailable

I don't think isTrailerFieldsAvailable is necessary.

An application has to wait until -1 is read (or a 0 length
request) before
calling any API else it will get an ISE. Then once it has
waited, we can
signal no trailers possibe with a null return and no trailers
sent with a
empty map.

If we had the isTrailerFieldsAvailable, then in Jetty it would
simply be
implemented as:

boolean isTrailerFieldsAvailable()
{
return this.trailers!=null;
}


--
Greg Wilkins <gregw@... <mailto:gregw@...>> CTO
http://webtide.com

On Mon, 22 May 2017 16:30:30 -0700, "Shing Wai Chan" <shing.wai.chan@...> said:

SW> To avoid the confusion, per discussion with Ed, I would rename the
SW> API as #isTrailerFieldsReady(). The API and the javadoc are as
SW> follows:

SW> /**
SW> * Return a boolean indicating whether trailer fields are ready to read
SW> * using {@link #getTrailerFields}.
SW> *
SW> * This method returns true if and only if all of the following conditions
SW> * are satisfied:
SW> * <ol type="a">
SW> * <li> the underlying protocol supports trailer fields. HTTP versions
SW> * less than 1.1 do not support trailer fields.
SW> * <li> the application has read all the request data and an EOF
SW> * indication has been returned from the {@link #getReader}
SW> * or {@link #getInputStream}, or the content length is zero,
SW> * <li> all the trailer fields sent by the client have been received.
SW> * Note that it is possible that the client has sent no trailer fields.
SW> * </ol>
SW> *
SW> * @implSpec
SW> * The default implementation returns false.
SW> *
SW> * @return a boolean whether trailer fields are ready to read
SW> *
SW> * @since Servlet 4.0
SW> */
SW> default public boolean isTrailerFieldsReady() {
SW> return false;
SW> }

This looks really great. As the Public Review Ballot starts tomorrow,
this proposal is the final proposal unless someone has a showstopper
compelling reason to change it.

Thanks to everone for considering this extremely late breaking change.

Ed

--
| edward.burns@... | office: +1 407 458 0017

On 23/05/17 00:30, Shing Wai Chan wrote:

On May 22, 2017, at 4:09 AM, Mark Thomas <markt@...> wrote:

On 22/05/17 06:52, Greg Wilkins wrote:

I think we need to say that the application had read to EOF or that
there is no content. It would be a bit silly to force an app to read to
EOF if content length is known to be 0

I'd also add "or if the container knows that the underlying protocol
does not support trailers”.

+1.

To avoid the confusion, per discussion with Ed, I would rename the API as #isTrailerFieldsReady().
The API and the javadoc are as follows:

This isn't quite what I had in mind. I was thinking that if the protocol
didn't support trailers this method would always return true so the app
could go ahead, call getTrailerFields() and get an empty Map.

When the protocol doesn't support trailers with the current wording, the
app can never be sure there won't be trailers to read at some point in
the future.

Mark

/**
* Return a boolean indicating whether trailer fields are ready to read
* using {@link #getTrailerFields}.
*
* This method returns true if and only if all of the following conditions
* are satisfied:
* <ol type="a">
* <li> the underlying protocol supports trailer fields. HTTP versions
* less than 1.1 do not support trailer fields.
* <li> the application has read all the request data and an EOF
* indication has been returned from the {@link #getReader}
* or {@link #getInputStream}, or the content length is zero,
* <li> all the trailer fields sent by the client have been received.
* Note that it is possible that the client has sent no trailer fields.
* </ol>
*
* @implSpec
* The default implementation returns false.
*
* @return a boolean whether trailer fields are ready to read
*
* @since Servlet 4.0
*/
default public boolean isTrailerFieldsReady() {
return false;
}

Thanks.
Shing Wai Chan

This would then meet the original use case I had in mind.

Mark

Cheers

On 19 May 2017 00:09, "Shing Wai Chan" <shing.wai.chan@...
<mailto:shing.wai.chan@...>> wrote:

Ok. I agree that we should drop the chunked encoding condition in my
previous proposal.
In this case, I will revise the javadoc of #isTrailerFieldsAvailable
as follows:

* This method returns true if and only if both of the following
conditions are
* satisfied:
* <ol type="a">
* <li> the application has read all the request data and an EOF
* indication has been returned from the {@link #getReader}
* or {@link #getInputStream}
* <li> all the trailer fields sent by the client have been
received.
* Note that it is possible that the client has sent no
trailer fields.
* </ol>

Thanks.
Shing Wai Chan

On May 18, 2017, at 2:17 PM, Stuart Douglas <sdouglas@...
<mailto:sdouglas@...>> wrote:

On Fri, May 19, 2017 at 7:05 AM, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>> wrote:

On May 18, 2017, at 1:32 PM, Stuart Douglas <sdouglas@...
<mailto:sdouglas@...>> wrote:

On Fri, May 19, 2017 at 6:06 AM, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>>
wrote:

Here is the javadoc for the proposed
#isTrailerFieldsAvailable() API:
/**
* Return a boolean indicating whether trailer fields are
available.
*
* This method returns true if and only if all the following
conditions
are
* satisfied:
* <ol type="a">
* <li> the request is using chunked transfer encoding

What about if HTTP/2 is in use?

Personally I think we should just drop this line, and just leave the
following two lines (although I don't feel super strongly about it
either way). With HTTP/2 trailers can always be sent so as HTTP/2
gains adoption this distinction will be meaningless, and if for some
reason the app wants to know if the request used chunking they can
just check the request headers.

Can we send HTTP2/trailer when it is not chunked transfer encoding?
I think we cannot.

In section 8.1 of RFC 7540:
4. optionally, one HEADERS frame, followed by zero or more
CONTINUATION frames containing the trailer-part, if
present (see
[RFC7230], Section 4.1.2).

HTTP/2 will never use chunked encoding. (8.1: HTTP/2 uses DATA frames
to carry message payloads. The "chunked" transfer encoding defined in
Section 4.1 of [RFC7230] MUST NOT be used in HTTP/2.).

But HTTP/2 does support trailers. Even though RFC 7230 explicitly
mentions chunking and RFC 7540 references this I believe RFC7230 is
referenced in relation to explaining the sematics of trailers, not the
chunked limitation (otherwise HTTP/2 would not reference trailers at
all, as chunking is prohibited).

In section 4.1.2 of RFC 7230:
A trailer allows the sender to include additional fields
at the end
of a chunked message in order to supply metadata that might be
dynamically generated while the message body is sent, such
as a
message integrity check, digital signature, or post-processing
status.

In Appendix B. Collected ABNF of RFC 7230, trailer-part is only
used in chunked-body.

If we drop the first condition, then we are allowing something
more general than HTTP2?

Yes, which is a good thing. We should really only care about
semantics, not the underlying transport technology. e.g. lots of
containers support AJP, which for the most part matches HTTP
semantics. If we start specifying everything in terms of specifics of
a given version of the HTTP protocol then support for this sort of
thing could become harder.

Stuart

I think we should keep the first condition in this case.
Thanks.
Shing Wai Chan

Stuart

* <li> the application has read all the request data and
an EOF
* indication has been returned from the {@link
#getReader}
* or {@link #getInputStream}
* <li> all the trailer fields sent by the client have been
received.
* Note that it is possible that the client has sent
no trailer
fields.
* </ol>
*
* @implSpec
* The default implementation returns false.
*
* @return a boolean whether trailer fields are available
*
* @since Servlet 4.0
*/
default public boolean isTrailerFieldsAvailable() {
return false;
}

For your convenience, I also include the corresponding updated
javadoc for
#getTrailerFields() API:
/**
* Get the request trailer fields.
*
* <p>The returned map is not backed by the {@code
HttpServletRequest}
object,
* so changes in the returned map are not reflected in the
* {@code HttpServletRequest} object, and vice-versa.</p>
*
* <p>{@link #isTrailerFieldsAvailable()} should be called
first to
determine
* if it is safe to call this method without causing an
exception.</p>
*
* @implSpec
* The default implementation throws IllegalStateException.
*
* @return A map of trailer fields in which all the keys are in
lowercase,
* regardless of the case they had at the protocol level. If
there are
no
* trailer fields, yet {@link #isTrailerFieldsAvailable} is
returning
true,
* the empty map is returned.
*
* @throws IllegalStateException if {@link
#isTrailerFieldsAvailable()}
is false
*
* @since Servlet 4.0
*/
default public Map<String, String> getTrailerFields() {
throw new IllegalStateException();
}

Please let me know your comment by COB tomorrow, May 19.
Thanks.
Shing Wai Chan


On May 17, 2017, at 3:37 PM, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>>
wrote:

SW> As MM (and MT) has suggested that we may like to add an API
to check
SW> whether trailer fields are available to read. So we may
like to add
SW> an API in HttpServletRequest as follows:
SW> boolean isTrailerFieldsAvailable();
SW> (Or boolean isTrailerAvailable(); )

SW> And calling getTrailerFields() before
isTrailerFieldsAvailable() ==
false
SW> will throw an IllegalStateException

And isTrailerFieldsAvailable() == true if and only if
a) the request is chunked
b) the application has read all the request data
b) the trailer fields have been received

Please let me know if you have any comment.
Shing Wai Chan

----- Original Message -----
From: shing.wai.chan@... <mailto:shing.wai.chan@...>
To: servlet-spec@javaee.groups.io
<mailto:servlet-spec@javaee.groups.io>
Sent: Monday, May 15, 2017 2:17:58 PM GMT -08:00 US/Canada Pacific
Subject: Re: [servlet-spec] read trailer

On April 21, 2017, we agree to choose NeverReturnNull option.
In this case,
Map<String, String> getTrailerFields()
will never return null.
(In general, we do not return null for API with Collection
return type.)

In this case, we will need to have #isTrailerFieldsAvailable().
Thanks.

Shing Wai Chan


On May 15, 2017, at 12:09 PM, Greg Wilkins <gregw@...
<mailto:gregw@...>> wrote:


On 15 May 2017 at 20:12, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>>
wrote:

isTrailerFieldsAvailable

I don't think isTrailerFieldsAvailable is necessary.

An application has to wait until -1 is read (or a 0 length
request) before
calling any API else it will get an ISE. Then once it has
waited, we can
signal no trailers possibe with a null return and no trailers
sent with a
empty map.

If we had the isTrailerFieldsAvailable, then in Jetty it would
simply be
implemented as:

boolean isTrailerFieldsAvailable()
{
return this.trailers!=null;
}


--
Greg Wilkins <gregw@... <mailto:gregw@...>> CTO
http://webtide.com

On May 23, 2017, at 8:29 AM, Mark Thomas <markt@...> wrote:

On 23/05/17 00:30, Shing Wai Chan wrote:

On May 22, 2017, at 4:09 AM, Mark Thomas <markt@...> wrote:

On 22/05/17 06:52, Greg Wilkins wrote:

I think we need to say that the application had read to EOF or that
there is no content. It would be a bit silly to force an app to read to
EOF if content length is known to be 0

I'd also add "or if the container knows that the underlying protocol
does not support trailers”.

+1.

To avoid the confusion, per discussion with Ed, I would rename the API as #isTrailerFieldsReady().
The API and the javadoc are as follows:

This isn't quite what I had in mind. I was thinking that if the protocol
didn't support trailers this method would always return true so the app
could go ahead, call getTrailerFields() and get an empty Map.

When the protocol doesn't support trailers with the current wording, the
app can never be sure there won't be trailers to read at some point in
the future.

If we do this, what happen when in non chunked encoding in HTTP/1.1?
It is also #isTrailerFieldsReady() == false all the time according the previous email.
Do we want to have #isTrailerFieldsReady() == true immediately (with empty Map) in this case?

Thanks.
Shing Wai Chan

Mark

/**
* Return a boolean indicating whether trailer fields are ready to read
* using {@link #getTrailerFields}.
*
* This method returns true if and only if all of the following conditions
* are satisfied:
* <ol type="a">
* <li> the underlying protocol supports trailer fields. HTTP versions
* less than 1.1 do not support trailer fields.
* <li> the application has read all the request data and an EOF
* indication has been returned from the {@link #getReader}
* or {@link #getInputStream}, or the content length is zero,
* <li> all the trailer fields sent by the client have been received.
* Note that it is possible that the client has sent no trailer fields.
* </ol>
*
* @implSpec
* The default implementation returns false.
*
* @return a boolean whether trailer fields are ready to read
*
* @since Servlet 4.0
*/
default public boolean isTrailerFieldsReady() {
return false;
}

Thanks.
Shing Wai Chan

This would then meet the original use case I had in mind.

Mark

Cheers

On 19 May 2017 00:09, "Shing Wai Chan" <shing.wai.chan@...
<mailto:shing.wai.chan@...>> wrote:

Ok. I agree that we should drop the chunked encoding condition in my
previous proposal.
In this case, I will revise the javadoc of #isTrailerFieldsAvailable
as follows:

* This method returns true if and only if both of the following
conditions are
* satisfied:
* <ol type="a">
* <li> the application has read all the request data and an EOF
* indication has been returned from the {@link #getReader}
* or {@link #getInputStream}
* <li> all the trailer fields sent by the client have been
received.
* Note that it is possible that the client has sent no
trailer fields.
* </ol>

Thanks.
Shing Wai Chan

On May 18, 2017, at 2:17 PM, Stuart Douglas <sdouglas@...
<mailto:sdouglas@...>> wrote:

On Fri, May 19, 2017 at 7:05 AM, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>> wrote:

On May 18, 2017, at 1:32 PM, Stuart Douglas <sdouglas@...
<mailto:sdouglas@...>> wrote:

On Fri, May 19, 2017 at 6:06 AM, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>>
wrote:

Here is the javadoc for the proposed
#isTrailerFieldsAvailable() API:
/**
* Return a boolean indicating whether trailer fields are
available.
*
* This method returns true if and only if all the following
conditions
are
* satisfied:
* <ol type="a">
* <li> the request is using chunked transfer encoding

What about if HTTP/2 is in use?

Personally I think we should just drop this line, and just leave the
following two lines (although I don't feel super strongly about it
either way). With HTTP/2 trailers can always be sent so as HTTP/2
gains adoption this distinction will be meaningless, and if for some
reason the app wants to know if the request used chunking they can
just check the request headers.

Can we send HTTP2/trailer when it is not chunked transfer encoding?
I think we cannot.

In section 8.1 of RFC 7540:
4. optionally, one HEADERS frame, followed by zero or more
CONTINUATION frames containing the trailer-part, if
present (see
[RFC7230], Section 4.1.2).

HTTP/2 will never use chunked encoding. (8.1: HTTP/2 uses DATA frames
to carry message payloads. The "chunked" transfer encoding defined in
Section 4.1 of [RFC7230] MUST NOT be used in HTTP/2.).

But HTTP/2 does support trailers. Even though RFC 7230 explicitly
mentions chunking and RFC 7540 references this I believe RFC7230 is
referenced in relation to explaining the sematics of trailers, not the
chunked limitation (otherwise HTTP/2 would not reference trailers at
all, as chunking is prohibited).

In section 4.1.2 of RFC 7230:
A trailer allows the sender to include additional fields
at the end
of a chunked message in order to supply metadata that might be
dynamically generated while the message body is sent, such
as a
message integrity check, digital signature, or post-processing
status.

In Appendix B. Collected ABNF of RFC 7230, trailer-part is only
used in chunked-body.

If we drop the first condition, then we are allowing something
more general than HTTP2?

Yes, which is a good thing. We should really only care about
semantics, not the underlying transport technology. e.g. lots of
containers support AJP, which for the most part matches HTTP
semantics. If we start specifying everything in terms of specifics of
a given version of the HTTP protocol then support for this sort of
thing could become harder.

Stuart

I think we should keep the first condition in this case.
Thanks.
Shing Wai Chan

Stuart

* <li> the application has read all the request data and
an EOF
* indication has been returned from the {@link
#getReader}
* or {@link #getInputStream}
* <li> all the trailer fields sent by the client have been
received.
* Note that it is possible that the client has sent
no trailer
fields.
* </ol>
*
* @implSpec
* The default implementation returns false.
*
* @return a boolean whether trailer fields are available
*
* @since Servlet 4.0
*/
default public boolean isTrailerFieldsAvailable() {
return false;
}

For your convenience, I also include the corresponding updated
javadoc for
#getTrailerFields() API:
/**
* Get the request trailer fields.
*
* <p>The returned map is not backed by the {@code
HttpServletRequest}
object,
* so changes in the returned map are not reflected in the
* {@code HttpServletRequest} object, and vice-versa.</p>
*
* <p>{@link #isTrailerFieldsAvailable()} should be called
first to
determine
* if it is safe to call this method without causing an
exception.</p>
*
* @implSpec
* The default implementation throws IllegalStateException.
*
* @return A map of trailer fields in which all the keys are in
lowercase,
* regardless of the case they had at the protocol level. If
there are
no
* trailer fields, yet {@link #isTrailerFieldsAvailable} is
returning
true,
* the empty map is returned.
*
* @throws IllegalStateException if {@link
#isTrailerFieldsAvailable()}
is false
*
* @since Servlet 4.0
*/
default public Map<String, String> getTrailerFields() {
throw new IllegalStateException();
}

Please let me know your comment by COB tomorrow, May 19.
Thanks.
Shing Wai Chan


On May 17, 2017, at 3:37 PM, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>>
wrote:

SW> As MM (and MT) has suggested that we may like to add an API
to check
SW> whether trailer fields are available to read. So we may
like to add
SW> an API in HttpServletRequest as follows:
SW> boolean isTrailerFieldsAvailable();
SW> (Or boolean isTrailerAvailable(); )

SW> And calling getTrailerFields() before
isTrailerFieldsAvailable() ==
false
SW> will throw an IllegalStateException

And isTrailerFieldsAvailable() == true if and only if
a) the request is chunked
b) the application has read all the request data
b) the trailer fields have been received

Please let me know if you have any comment.
Shing Wai Chan

----- Original Message -----
From: shing.wai.chan@... <mailto:shing.wai.chan@...>
To: servlet-spec@javaee.groups.io
<mailto:servlet-spec@javaee.groups.io>
Sent: Monday, May 15, 2017 2:17:58 PM GMT -08:00 US/Canada Pacific
Subject: Re: [servlet-spec] read trailer

On April 21, 2017, we agree to choose NeverReturnNull option.
In this case,
Map<String, String> getTrailerFields()
will never return null.
(In general, we do not return null for API with Collection
return type.)

In this case, we will need to have #isTrailerFieldsAvailable().
Thanks.

Shing Wai Chan


On May 15, 2017, at 12:09 PM, Greg Wilkins <gregw@...
<mailto:gregw@...>> wrote:


On 15 May 2017 at 20:12, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>>
wrote:

isTrailerFieldsAvailable

I don't think isTrailerFieldsAvailable is necessary.

An application has to wait until -1 is read (or a 0 length
request) before
calling any API else it will get an ISE. Then once it has
waited, we can
signal no trailers possibe with a null return and no trailers
sent with a
empty map.

If we had the isTrailerFieldsAvailable, then in Jetty it would
simply be
implemented as:

boolean isTrailerFieldsAvailable()
{
return this.trailers!=null;
}


--
Greg Wilkins <gregw@... <mailto:gregw@...>> CTO
http://webtide.com

On 23/05/2017 17:25, Shing Wai Chan wrote:

On May 23, 2017, at 8:29 AM, Mark Thomas <markt@...> wrote:

On 23/05/17 00:30, Shing Wai Chan wrote:

On May 22, 2017, at 4:09 AM, Mark Thomas <markt@...> wrote:

On 22/05/17 06:52, Greg Wilkins wrote:

I think we need to say that the application had read to EOF or that
there is no content. It would be a bit silly to force an app to read to
EOF if content length is known to be 0

I'd also add "or if the container knows that the underlying protocol
does not support trailers”.

+1.

To avoid the confusion, per discussion with Ed, I would rename the API as #isTrailerFieldsReady().
The API and the javadoc are as follows:

This isn't quite what I had in mind. I was thinking that if the protocol
didn't support trailers this method would always return true so the app
could go ahead, call getTrailerFields() and get an empty Map.

When the protocol doesn't support trailers with the current wording, the
app can never be sure there won't be trailers to read at some point in
the future.

If we do this, what happen when in non chunked encoding in HTTP/1.1?

It returns true straight away.

It is also #isTrailerFieldsReady() == false all the time according the previous email.
Do we want to have #isTrailerFieldsReady() == true immediately (with empty Map) in this case?

That is exactly what I was thinking. Otherwise it returns false. So the
app reads the request body. It still returns false. So the app waits for
the trailers to be processed. It still returns false. The app has no way
of knowing this method will never return true.

Now consider my suggested changed.

It returns true. App reads the Map. The Map is empty. The app knows
there are no trailers (it doesn't care why there are no trailers). The
app moves on.

Mark

Thanks.
Shing Wai Chan

Mark

/**
* Return a boolean indicating whether trailer fields are ready to read
* using {@link #getTrailerFields}.
*
* This method returns true if and only if all of the following conditions
* are satisfied:
* <ol type="a">
* <li> the underlying protocol supports trailer fields. HTTP versions
* less than 1.1 do not support trailer fields.
* <li> the application has read all the request data and an EOF
* indication has been returned from the {@link #getReader}
* or {@link #getInputStream}, or the content length is zero,
* <li> all the trailer fields sent by the client have been received.
* Note that it is possible that the client has sent no trailer fields.
* </ol>
*
* @implSpec
* The default implementation returns false.
*
* @return a boolean whether trailer fields are ready to read
*
* @since Servlet 4.0
*/
default public boolean isTrailerFieldsReady() {
return false;
}

Thanks.
Shing Wai Chan

This would then meet the original use case I had in mind.

Mark

Cheers

On 19 May 2017 00:09, "Shing Wai Chan" <shing.wai.chan@...
<mailto:shing.wai.chan@...>> wrote:

Ok. I agree that we should drop the chunked encoding condition in my
previous proposal.
In this case, I will revise the javadoc of #isTrailerFieldsAvailable
as follows:

* This method returns true if and only if both of the following
conditions are
* satisfied:
* <ol type="a">
* <li> the application has read all the request data and an EOF
* indication has been returned from the {@link #getReader}
* or {@link #getInputStream}
* <li> all the trailer fields sent by the client have been
received.
* Note that it is possible that the client has sent no
trailer fields.
* </ol>

Thanks.
Shing Wai Chan

On May 18, 2017, at 2:17 PM, Stuart Douglas <sdouglas@...
<mailto:sdouglas@...>> wrote:

On Fri, May 19, 2017 at 7:05 AM, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>> wrote:

On May 18, 2017, at 1:32 PM, Stuart Douglas <sdouglas@...
<mailto:sdouglas@...>> wrote:

On Fri, May 19, 2017 at 6:06 AM, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>>
wrote:

Here is the javadoc for the proposed
#isTrailerFieldsAvailable() API:
/**
* Return a boolean indicating whether trailer fields are
available.
*
* This method returns true if and only if all the following
conditions
are
* satisfied:
* <ol type="a">
* <li> the request is using chunked transfer encoding

What about if HTTP/2 is in use?

Personally I think we should just drop this line, and just leave the
following two lines (although I don't feel super strongly about it
either way). With HTTP/2 trailers can always be sent so as HTTP/2
gains adoption this distinction will be meaningless, and if for some
reason the app wants to know if the request used chunking they can
just check the request headers.

Can we send HTTP2/trailer when it is not chunked transfer encoding?
I think we cannot.

In section 8.1 of RFC 7540:
4. optionally, one HEADERS frame, followed by zero or more
CONTINUATION frames containing the trailer-part, if
present (see
[RFC7230], Section 4.1.2).

HTTP/2 will never use chunked encoding. (8.1: HTTP/2 uses DATA frames
to carry message payloads. The "chunked" transfer encoding defined in
Section 4.1 of [RFC7230] MUST NOT be used in HTTP/2.).

But HTTP/2 does support trailers. Even though RFC 7230 explicitly
mentions chunking and RFC 7540 references this I believe RFC7230 is
referenced in relation to explaining the sematics of trailers, not the
chunked limitation (otherwise HTTP/2 would not reference trailers at
all, as chunking is prohibited).

In section 4.1.2 of RFC 7230:
A trailer allows the sender to include additional fields
at the end
of a chunked message in order to supply metadata that might be
dynamically generated while the message body is sent, such
as a
message integrity check, digital signature, or post-processing
status.

In Appendix B. Collected ABNF of RFC 7230, trailer-part is only
used in chunked-body.

If we drop the first condition, then we are allowing something
more general than HTTP2?

Yes, which is a good thing. We should really only care about
semantics, not the underlying transport technology. e.g. lots of
containers support AJP, which for the most part matches HTTP
semantics. If we start specifying everything in terms of specifics of
a given version of the HTTP protocol then support for this sort of
thing could become harder.

Stuart

I think we should keep the first condition in this case.
Thanks.
Shing Wai Chan

Stuart

* <li> the application has read all the request data and
an EOF
* indication has been returned from the {@link
#getReader}
* or {@link #getInputStream}
* <li> all the trailer fields sent by the client have been
received.
* Note that it is possible that the client has sent
no trailer
fields.
* </ol>
*
* @implSpec
* The default implementation returns false.
*
* @return a boolean whether trailer fields are available
*
* @since Servlet 4.0
*/
default public boolean isTrailerFieldsAvailable() {
return false;
}

For your convenience, I also include the corresponding updated
javadoc for
#getTrailerFields() API:
/**
* Get the request trailer fields.
*
* <p>The returned map is not backed by the {@code
HttpServletRequest}
object,
* so changes in the returned map are not reflected in the
* {@code HttpServletRequest} object, and vice-versa.</p>
*
* <p>{@link #isTrailerFieldsAvailable()} should be called
first to
determine
* if it is safe to call this method without causing an
exception.</p>
*
* @implSpec
* The default implementation throws IllegalStateException.
*
* @return A map of trailer fields in which all the keys are in
lowercase,
* regardless of the case they had at the protocol level. If
there are
no
* trailer fields, yet {@link #isTrailerFieldsAvailable} is
returning
true,
* the empty map is returned.
*
* @throws IllegalStateException if {@link
#isTrailerFieldsAvailable()}
is false
*
* @since Servlet 4.0
*/
default public Map<String, String> getTrailerFields() {
throw new IllegalStateException();
}

Please let me know your comment by COB tomorrow, May 19.
Thanks.
Shing Wai Chan


On May 17, 2017, at 3:37 PM, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>>
wrote:

SW> As MM (and MT) has suggested that we may like to add an API
to check
SW> whether trailer fields are available to read. So we may
like to add
SW> an API in HttpServletRequest as follows:
SW> boolean isTrailerFieldsAvailable();
SW> (Or boolean isTrailerAvailable(); )

SW> And calling getTrailerFields() before
isTrailerFieldsAvailable() ==
false
SW> will throw an IllegalStateException

And isTrailerFieldsAvailable() == true if and only if
a) the request is chunked
b) the application has read all the request data
b) the trailer fields have been received

Please let me know if you have any comment.
Shing Wai Chan

----- Original Message -----
From: shing.wai.chan@... <mailto:shing.wai.chan@...>
To: servlet-spec@javaee.groups.io
<mailto:servlet-spec@javaee.groups.io>
Sent: Monday, May 15, 2017 2:17:58 PM GMT -08:00 US/Canada Pacific
Subject: Re: [servlet-spec] read trailer

On April 21, 2017, we agree to choose NeverReturnNull option.
In this case,
Map<String, String> getTrailerFields()
will never return null.
(In general, we do not return null for API with Collection
return type.)

In this case, we will need to have #isTrailerFieldsAvailable().
Thanks.

Shing Wai Chan


On May 15, 2017, at 12:09 PM, Greg Wilkins <gregw@...
<mailto:gregw@...>> wrote:


On 15 May 2017 at 20:12, Shing Wai Chan
<shing.wai.chan@... <mailto:shing.wai.chan@...>>
wrote:

isTrailerFieldsAvailable

I don't think isTrailerFieldsAvailable is necessary.

An application has to wait until -1 is read (or a 0 length
request) before
calling any API else it will get an ISE. Then once it has
waited, we can
signal no trailers possibe with a null return and no trailers
sent with a
empty map.

If we had the isTrailerFieldsAvailable, then in Jetty it would
simply be
implemented as:

boolean isTrailerFieldsAvailable()
{
return this.trailers!=null;
}


--
Greg Wilkins <gregw@... <mailto:gregw@...>> CTO
http://webtide.com