M
Matt Todd
= Halcyon
== JSON Server App Framework
Halcyon is a JSON Web App Framework built on Rack for speed and light weight.
For more information, check out our website at
http://halcyon.rubyforge.org/ or go straight to the RDocs:
http://halcyon.rubyforge.org/doc/.
For bug submissions, feature requests, or to submit patches, visit
http://halcyon.lighthouseapp.com/, gracefully contributed by the
awesome people at Active Reload! Find them and their services at
http://activereload.net/.
=== Announcement
A lot of the huge improvements planned for 0.4.0 have been shifted
back to 0.5.0 in order to go ahead and push out the currently
implemented improvements but not prevent a full release due to the
time commitment required for the planned improvements.
Release 0.5.0 will include a great deal of restructuring and improve
support for Thin primarily but also remove a lot of functionality
unneeded by Halcyon which is managed by servers like Thin. The next
major release will also make enormous improvements to client-side
integration, etc.
Follow along with (or participate in) Halcyon's development at
http://halcyon.lighthouseapp.com/projects/7222-halcyon/milestones/current
Release Name: halcyon-0.4.0
Notes:
This is a relatively minor update with a focus on improving code
quality and structure.
* Changed how methods are defined (removing the necessary for a params
argument), opting for a method named params to provide the same
functionality.
* Added GET and POST data convenience methods (closing ticket #10).
Makes post[:foo] and get[:bar] possible.
* Added primitive support for Basic authentication for servers and clients.
* Uses Thin by default if it is installed, Mongrel otherwise.
* Refactored some dirty code for more established alternatives from
merb/core_ext which is already a dependency. Cleans up some code quite
well.
* Added the root configuration option as the applications current
active directory. This is to provide the ability to change the active
root via a commandline or config file option.
* Cleaned up the Client request methods in order to allow for headers
to be passed along with them and to be set via callback.
* Added startup and shutdown hooks for apps inheriting Server::Base to
provide a simple way to perform important tasks without having to
overwrite initialize.
* Updated documentation, specs, and examples to match changes.
* Added a Thanks To section in the README for contributors.
Bug Fixes
* Minor improvements to the Basic Authentication
(Halcyon::Server::Auth::Basic) implementation and interface.
* Made sure the port value passed to the Mongrel handler (via Rack)
was an integer, fixing #14. Thanks to ramdestedt for the fix.
* Added URI dependency for the Router class erroneously left out.
Thanks Elliott Cable.
* Fixed some display issues with Exceptions in order to display properly.
* Fixed a typo that Bill Marquette spotted.
== Dependencies
NOTE: The JSON dependency is now recorded as the json_pure gem in the
Gem spec and will only automatically install that gem. To get faster
parsing and better performance, manually install the json gem with
"gem install json". This was done to support platforms that wouldn't
natively build the JSON extensions. Internally the JSON extensions are
given precedence, though it fails gracefully and will use the pure
Ruby JSON gem.
* Rack >= 0.2.0
* JSON >= 1.1.1
* Merb >= 0.4.1
Halcyon is built on top of Rack for swift delivery of very small
informational payloads transmitted through JSON. Merb routes are
employed to make designing app structures easier with routes.
= From the Readme
== Quick start
There's not much to Halcyon. I've put a good deal of time into
fleshing out the RDocs so check out the documentation and the example
directory.
Halcyon is the sister project of Aurora SAS, a simple authentication
server to manage authentication, session management, and user roles
and permissions. It is still very early in development (as Halcyon was
a prerequisite) but there should be some interesting code from that
project to let you see just what Halcyon is capable. Stay tuned!
== Installing with RubyGems
A Gem of Halcyon is available. You can install it with:
$ sudo gem install halcyon
== Usage
The halcyon command will assist you for running the server. Just run:
$ halcyon -d -p 3800 example/simple
You may need to cd into the project directory, or, alternatively, you
can cp the files out into your tmp folder and work from there. If
you'd like to just cd, +gem which halcyon+ will tell you where to find
the Gem directory.
Once you've gotten the server running, pull open your browser, point
it to localhost:3800/ and see what happens. Take a look at the source
and try to access the other routes and see how things work. Notice the
response in the browser.
Once you've familiarized yourself with that, kill the server (Ctl+C)
and start it again without the debugging switch: -d. (+halcyon -h+ for
usage help.)
$ halcyon -p 3800 example/simple
Now pull it up again in the browser. You'll notice right away that it
blocks all access from any user agent that doesn't meet its
requirements (but debug mode disabled that feature).
The good news about that is that it reduces a lot of the garbage
signals that a normal server might have to endure, but since we're
working with specialized applications, it's perfectly reasonable to be
very stingy about who we talk to.
Now, pull up IRB and require RubyGems and Halcyon (as halcon/client).
Now run the following:
And that is some very simple stuff you can do with the Client library.
The Client library is meant to be used in larger applications where a
fraction of functionality requires smaller and faster updates or
quicker responses in a lightweight protocol, perfect for sending
authentication information (over secure channels, of course) or
getting updates on various monitoring sources.
Read more in the RDocs, there's a lot more there to find out. The best
way to learn, though, is to play, and I like to play, so, go for it.
== Contact
Please mail bugs, suggestions and patches to <[email protected]>.
You are also welcome to join the halcyon channel on irc.freenode.net.
Our website is up so stop by and check out what's going down. Our
address is halcyon.rubyforge.org/. On there you will find information
about our mailing list as well, so do stop by.
== License and Copyright
Copyright (C) 2007 Matt Todd <purl.org/net/maraby>.
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
== Links
Halcyon: <halcyon.rubyforge.org/>
Aurora: <aurora.rubyforge.org/>
Rack: <rack.rubyforge.org/>
Merb: <merbivore.org/>
JSON: <json.rubyforge.org/>
Matt Todd: <maraby.org/>
== JSON Server App Framework
Halcyon is a JSON Web App Framework built on Rack for speed and light weight.
For more information, check out our website at
http://halcyon.rubyforge.org/ or go straight to the RDocs:
http://halcyon.rubyforge.org/doc/.
For bug submissions, feature requests, or to submit patches, visit
http://halcyon.lighthouseapp.com/, gracefully contributed by the
awesome people at Active Reload! Find them and their services at
http://activereload.net/.
=== Announcement
A lot of the huge improvements planned for 0.4.0 have been shifted
back to 0.5.0 in order to go ahead and push out the currently
implemented improvements but not prevent a full release due to the
time commitment required for the planned improvements.
Release 0.5.0 will include a great deal of restructuring and improve
support for Thin primarily but also remove a lot of functionality
unneeded by Halcyon which is managed by servers like Thin. The next
major release will also make enormous improvements to client-side
integration, etc.
Follow along with (or participate in) Halcyon's development at
http://halcyon.lighthouseapp.com/projects/7222-halcyon/milestones/current
Release Name: halcyon-0.4.0
Notes:
This is a relatively minor update with a focus on improving code
quality and structure.
* Changed how methods are defined (removing the necessary for a params
argument), opting for a method named params to provide the same
functionality.
* Added GET and POST data convenience methods (closing ticket #10).
Makes post[:foo] and get[:bar] possible.
* Added primitive support for Basic authentication for servers and clients.
* Uses Thin by default if it is installed, Mongrel otherwise.
* Refactored some dirty code for more established alternatives from
merb/core_ext which is already a dependency. Cleans up some code quite
well.
* Added the root configuration option as the applications current
active directory. This is to provide the ability to change the active
root via a commandline or config file option.
* Cleaned up the Client request methods in order to allow for headers
to be passed along with them and to be set via callback.
* Added startup and shutdown hooks for apps inheriting Server::Base to
provide a simple way to perform important tasks without having to
overwrite initialize.
* Updated documentation, specs, and examples to match changes.
* Added a Thanks To section in the README for contributors.
Bug Fixes
* Minor improvements to the Basic Authentication
(Halcyon::Server::Auth::Basic) implementation and interface.
* Made sure the port value passed to the Mongrel handler (via Rack)
was an integer, fixing #14. Thanks to ramdestedt for the fix.
* Added URI dependency for the Router class erroneously left out.
Thanks Elliott Cable.
* Fixed some display issues with Exceptions in order to display properly.
* Fixed a typo that Bill Marquette spotted.
== Dependencies
NOTE: The JSON dependency is now recorded as the json_pure gem in the
Gem spec and will only automatically install that gem. To get faster
parsing and better performance, manually install the json gem with
"gem install json". This was done to support platforms that wouldn't
natively build the JSON extensions. Internally the JSON extensions are
given precedence, though it fails gracefully and will use the pure
Ruby JSON gem.
* Rack >= 0.2.0
* JSON >= 1.1.1
* Merb >= 0.4.1
Halcyon is built on top of Rack for swift delivery of very small
informational payloads transmitted through JSON. Merb routes are
employed to make designing app structures easier with routes.
= From the Readme
== Quick start
There's not much to Halcyon. I've put a good deal of time into
fleshing out the RDocs so check out the documentation and the example
directory.
Halcyon is the sister project of Aurora SAS, a simple authentication
server to manage authentication, session management, and user roles
and permissions. It is still very early in development (as Halcyon was
a prerequisite) but there should be some interesting code from that
project to let you see just what Halcyon is capable. Stay tuned!
== Installing with RubyGems
A Gem of Halcyon is available. You can install it with:
$ sudo gem install halcyon
== Usage
The halcyon command will assist you for running the server. Just run:
$ halcyon -d -p 3800 example/simple
You may need to cd into the project directory, or, alternatively, you
can cp the files out into your tmp folder and work from there. If
you'd like to just cd, +gem which halcyon+ will tell you where to find
the Gem directory.
Once you've gotten the server running, pull open your browser, point
it to localhost:3800/ and see what happens. Take a look at the source
and try to access the other routes and see how things work. Notice the
response in the browser.
Once you've familiarized yourself with that, kill the server (Ctl+C)
and start it again without the debugging switch: -d. (+halcyon -h+ for
usage help.)
$ halcyon -p 3800 example/simple
Now pull it up again in the browser. You'll notice right away that it
blocks all access from any user agent that doesn't meet its
requirements (but debug mode disabled that feature).
The good news about that is that it reduces a lot of the garbage
signals that a normal server might have to endure, but since we're
working with specialized applications, it's perfectly reasonable to be
very stingy about who we talk to.
Now, pull up IRB and require RubyGems and Halcyon (as halcon/client).
Now run the following:
And that is some very simple stuff you can do with the Client library.
The Client library is meant to be used in larger applications where a
fraction of functionality requires smaller and faster updates or
quicker responses in a lightweight protocol, perfect for sending
authentication information (over secure channels, of course) or
getting updates on various monitoring sources.
Read more in the RDocs, there's a lot more there to find out. The best
way to learn, though, is to play, and I like to play, so, go for it.
== Contact
Please mail bugs, suggestions and patches to <[email protected]>.
You are also welcome to join the halcyon channel on irc.freenode.net.
Our website is up so stop by and check out what's going down. Our
address is halcyon.rubyforge.org/. On there you will find information
about our mailing list as well, so do stop by.
== License and Copyright
Copyright (C) 2007 Matt Todd <purl.org/net/maraby>.
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
== Links
Halcyon: <halcyon.rubyforge.org/>
Aurora: <aurora.rubyforge.org/>
Rack: <rack.rubyforge.org/>
Merb: <merbivore.org/>
JSON: <json.rubyforge.org/>
Matt Todd: <maraby.org/>