Improve documentation about IO abstraction

Hello!

Recently I’d read the documentation about IO abstraction and found two things which can be improved:

First, it is said

Shrine is able to upload any IO-like object that implement methods #read, #rewind, #eof? and #close whose behavior matches the IO class.

I’ve implemented an object with such methods, but it does not work because Shrine requires to implement one more method - #size. It would be great to fix the documentation.

Second, when I upload an attachment from Rails, Shrine can extract file name and content type from headers and URL. Unfortunately, I’ve found no information about how to implement such behavior with a custom IO object. It would be great to add some docs which will explain how Shrine will use content_type and original_filename methods when they exist.

I’ve implemented an object with such methods, but it does not work because Shrine requires to implement one more method - #size . It would be great to fix the documentation.

Where did the NoMethodError error occur?

The #size method was required in the past, but it’s not anymore. You can see here that we’re enforcing only the 4 other methods, and there is a test for that.

Some storage classes might rely on #size, but that’s not something Shrine has control over. Shrine’s built in S3 storage handles IO objects not responding to #size.

I’m open to mentioning that #size might be required in some scenarios, but I first want to be clear what those are.

Unfortunately, I’ve found no information about how to implement such behavior with a custom IO object. It would be great to add some docs which will explain how Shrine will use content_type and original_filename methods when they exist.

This is mentioned in the Extracting Metadata guide, just above the “Accessing Metadata” heading.

@janko thanks for your answer!

Where did the NoMethodError error occur?

I use shrine with Rails app as it is described in readme. I’d defined uploader, attached it to the model and write something like

user.avatar = avatar

avatar is an object without size method. In this case I get such error: HTTP::RequestError (IO object must respond to #size).

Shrine version is 3.2.2. I’ve checked the behavior of 3.3.0 - it’s the same.

This is mentioned in the Extracting Metadata guide, just above the “Accessing Metadata” heading.

Thanks! But for me as a new user of shrine it was not obvious. Could we just add some sort of cross link from one section to another?

In this case I get such error: HTTP::RequestError (IO object must respond to #size) .

Yeah, in this case you seem to be using a storage that uses http.rb, which requires IO objects to respond to #size by default. I’m open to amending the docs to state that #size is required in some cases.

But for me as a new user of shrine it was not obvious. Could we just add some sort of cross link from one section to another?

The “Metadata” section in the Getting Started guide already links to the Extracting Metadata guide in the “Other metadata” subsection. But I’m open to making the cross link more obvious if you have ideas.