New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rack SPEC doc unclear to me, help? #347

Closed
jordansissel opened this Issue Feb 28, 2012 · 3 comments

Comments

Projects
None yet
2 participants
@jordansissel

jordansissel commented Feb 28, 2012

These are all related to http://rack.rubyforge.org/doc/SPEC.html

  • HTTP_ Variables - the spec doesn't specify how the headers should be translated. I looked at the source for Thin and observed that a header 'Foo-Bar' will be saved as HTTP_FOO_BAR (I think). Is translation correct? uppercase and replace dashes with underscores?
  • The 'rack.input' stream. Should 'gets' behave like IO#gets? (Return a line of text)
  • The 'rack.input' stream. Any particular behavior for 'each'? Or can any length string be returned?
  • The 'rack.input' stream. What is meant by "the beginning" in "It rewinds the input stream back to the beginning"? The beginning of what time? the last N bytes? the start of the request? the start of the SSL handshake? If any of these, how long is the stream expected to keep this stuff buffered? If the request is an HTTP Upgrade (say, to websockets), is rewind still expected to work, and for how long?
@jordansissel

This comment has been minimized.

Show comment
Hide comment
@jordansissel

jordansissel Feb 28, 2012

obviously, if the spec details things I believe it does not, let me know as I might have misread things :)

jordansissel commented Feb 28, 2012

obviously, if the spec details things I believe it does not, let me know as I might have misread things :)

@rkh

This comment has been minimized.

Show comment
Hide comment
@rkh

rkh Feb 28, 2012

Member

On Feb 28, 2012, at 8:34 AM, Jordan Sissel wrote:

These are all related to http://rack.rubyforge.org/doc/SPEC.html

  • HTTP_ Variables - the spec doesn't specify how the headers should be translated. I looked at the source for Thin and observed that a header 'Foo-Bar' will be saved as HTTP_FOO_BAR (I think). Is translation correct? uppercase and replace dashes with underscores?

It is implicitly specified by saying that "The environment must be an instance of Hash that includes CGI-like headers". The reasoning behind this: Environment variables may not contain underscores and are usually upper case. Moreover, headers are case insensitive. Note that Rack is designed to also work well with CGI.

  • The 'rack.input' stream. Should 'gets' behave like IO#gets? (Return a line of text)

I don't think it has to be a line, though that's convention.

"gets must be called without arguments and return a string, or nil on EOF."

  • The 'rack.input' stream. Any particular behavior for 'each'? Or can any length string be returned?

I think each could even yield indefinite, though most middleware assumes otherwise. This includes middleware and tools that ship with Rack and are used by major frameworks and libraries. Most servers fix this by either passing in a real IO object or a StringIO.

  • The 'rack.input' stream. What is meant by "the beginning" in "It rewinds the input stream back to the beginning"? The beginning of what time? the last N bytes? the start of the request? the start of the SSL handshake? If any of these, how long is the stream expected to keep this stuff buffered? If the request is an HTTP Upgrade (say, to websockets), is rewind still expected to work, and for how long?

Rewind to the beginning of the request. Yes, this makes a few things complicated. Also, you might do best simply not to use Rack for WebSockets. Most parts for Rack (including Rack::Request) assume that it can read the complete request and for instance parse params from it. Moreover, it assumes that it can read the complete request more than once, which is crucial at the moment, as Rack does not come with a sufficient reflection API to figure out whether some middleware somewhere already read from the stream or not.

Konstantin


Reply to this email directly or view it on GitHub:
#347

Member

rkh commented Feb 28, 2012

On Feb 28, 2012, at 8:34 AM, Jordan Sissel wrote:

These are all related to http://rack.rubyforge.org/doc/SPEC.html

  • HTTP_ Variables - the spec doesn't specify how the headers should be translated. I looked at the source for Thin and observed that a header 'Foo-Bar' will be saved as HTTP_FOO_BAR (I think). Is translation correct? uppercase and replace dashes with underscores?

It is implicitly specified by saying that "The environment must be an instance of Hash that includes CGI-like headers". The reasoning behind this: Environment variables may not contain underscores and are usually upper case. Moreover, headers are case insensitive. Note that Rack is designed to also work well with CGI.

  • The 'rack.input' stream. Should 'gets' behave like IO#gets? (Return a line of text)

I don't think it has to be a line, though that's convention.

"gets must be called without arguments and return a string, or nil on EOF."

  • The 'rack.input' stream. Any particular behavior for 'each'? Or can any length string be returned?

I think each could even yield indefinite, though most middleware assumes otherwise. This includes middleware and tools that ship with Rack and are used by major frameworks and libraries. Most servers fix this by either passing in a real IO object or a StringIO.

  • The 'rack.input' stream. What is meant by "the beginning" in "It rewinds the input stream back to the beginning"? The beginning of what time? the last N bytes? the start of the request? the start of the SSL handshake? If any of these, how long is the stream expected to keep this stuff buffered? If the request is an HTTP Upgrade (say, to websockets), is rewind still expected to work, and for how long?

Rewind to the beginning of the request. Yes, this makes a few things complicated. Also, you might do best simply not to use Rack for WebSockets. Most parts for Rack (including Rack::Request) assume that it can read the complete request and for instance parse params from it. Moreover, it assumes that it can read the complete request more than once, which is crucial at the moment, as Rack does not come with a sufficient reflection API to figure out whether some middleware somewhere already read from the stream or not.

Konstantin


Reply to this email directly or view it on GitHub:
#347

@jordansissel

This comment has been minimized.

Show comment
Hide comment
@jordansissel

jordansissel Feb 28, 2012

I'll stay away from Rack, for now, based on your last comments about the expected behavior of the input stream.

These details were super helpful, thanks :)

jordansissel commented Feb 28, 2012

I'll stay away from Rack, for now, based on your last comments about the expected behavior of the input stream.

These details were super helpful, thanks :)

@rkh rkh closed this Feb 28, 2012

marcandre pushed a commit to marcandre/backports_bot that referenced this issue Dec 16, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment