Gap in documentation for serving static assets

[algofoogle]

When learning Plezi, it's important to know how to serve static assets, in order to try making a primitive usable application example.

Gaps in the documentation make it hard to understand. I'm happy to help improve the documentation, but I need some clues :)

If I can fix this, I think it will help users understand how to take examples in irb and then later understand how they work with Rack, etc.

I'm looking at: http://www.plezi.io/docs/routes

• Fine: From the heading "Defining a Route" down to (and including) "Re-Write Routes" it makes sense, and they work in irb.
• Confusing: The Plezi Assets Route.

I tried many combinations using the documentation above, but nothing seems to work as described. My main confusion is: In irb, what is a single, simple, complete example of serving a static asset? It might be a JPEG file, CSS file, or JS file that I've already got in my directory.

I can provide more examples of what I've tried, but this is what I assume would work, according to the documentation:

1. Make this directory/file structure:

   test/
       assets/images/example1.jpg
       public/images/example2.jpg
   

2. Go into the test directory
3. Run irb
4. Paste this code into the IRB, which exits at the end and starts running the Plezi/Iodine server:

   require 'plezi'
   class HelloController
     def index; "Hello, World!"; end
     def show;  "Oh, hello #{params['id']}"; end
   end
   Plezi.route "/hi", HelloController
   exit

5. Prove that the controller works by going to:
   • http://localhost:3000/ => Error 404, not found. -- OK, fine, that route isn't handled yet.
   • http://localhost:3000/hi => Hello, World! -- Good, index method was called.
   • http://localhost:3000/hi/Anton => Oh, hello Anton -- Good, show method was called with implicit id parameter.
6. But now, how do I access my example.jpg (from point 1 above)? These paths all give the 404 error:
   • http://localhost:3000/example1.jpg
   • http://localhost:3000/images/example1.jpg
   • http://localhost:3000/public/example1.jpg
   • http://localhost:3000/public/images/example1.jpg
   • http://localhost:3000/assets/images/example1.jpg
   • ...and I tried all of these with example2.jpg too, which also all gave 404 errors.
7. I also tried modifying the code like this, but it made no difference:

   require 'plezi'
   require 'pathname'; Root = Pathname.new(File.dirname(__FILE__)).expand_path
   Plezi.assets = Root.join('assets').to_s
   class HelloController
     def index; "Hello, World!"; end
     def show;  "Oh, hello #{params['id']}"; end
   end
   Plezi.route "/hi", HelloController
   
   # I also tried adding this, but it didn't help either:
   #Plezi.route '/assets', :assets
   
   exit

I understand that it is perhaps not sensible to run examples in irb that we expect to throw away, while also relying on actual permanent files (for assets). However, as someone learning this it is easier to understand a single app.rb file alongside other asset files, before we make the leap to Rack.

[boazsegev]

Hi @algofoogle ,

I apologize if things take time - these are busy times for me.

Perhaps the definition of "assets" in the documentation is unclear, but "assets" refers only to dynamic assets that require "rendering" or "baking".

This would be SCSS files that need to be rendered as CSS files, or CoffeeScript files that need to be rendered as Javascript files.

The :assets router will not render any jpg files, since they don't require to be rendered.

You could, of course, Plezi:: AssetBaker.register a "driver" for jpg files (that driver would do nothing except load the file to memory)...

...but the correct way to serve static files would be to setup the server to serve static files from the Public folder.

If you're using the latest version of Plezi's default server (iodine, 0.7.38), the correct way to set up a public folder (for serving static files) would be to either (in code / irb):

Iodine::DEFAULT_HTTP_ARGS[:public] = './public'

Or, from the command line, when starting iodine:

$ iodine -www ./public

You can run iodine -? or iodine -h to list all the command line interface options.

P.S.

Also, I should note that most of Plezi's features (except for the router, renderer and asset baking) have been transferred into the iodine gem (the default server).

Originally, Plezi "hijacked" connection to enable real-time updates and pub/sub. However, this resulted in code duplication between the server IO management system and the WebSocket management system - so both systems were unified under the "iodine" Ruby server.

Since not many people actually use Plezi, the current long term plan is to move as much as possible from Plezi to the iodine server, so Plezi remains as simple as possible and requires minimal maintenance. The iodine server will also move from development to maintenance once it matures (as it appears to have almost done).

[amm-catapult]

Ah great, thanks @boazsegev :) Iodine::DEFAULT_HTTP_ARGS[:public] = './public' is what I needed. I will try that soon.

I had previously submitted a pull request for getting involved with improving documentation. If you are happy with that one, I will try to submit another that includes more about assets, asset baking, and perhaps this example too.

I was interested first in Plezi because I didn't like having to set up such a huge stack as Rails 6 just to start learning how to do some things with WebSockets in Ruby. Now I will study more about iodine, too :)

Thanks!

[boazsegev]

Thanks for the PR and your kind help.

Have fun and good luck with everything! 👏🏻👏🏻👍🏻