Taknado: Eugene Bolshakov, Blog

Paperclip Tweaks: Convert options, Delete & Rename Attachments, Validate content type and image dimensions

2009-10-01T00:00:00+04:00

I use Paperclip for attachments in my Rails applications and I find that most of the time I end up using the following tweaks.

Convert Options

When you define attachments in your model, one of the available parameters is “convert_options” which is basically a string of parameters that is passed to image magick when thumbnails are created. I use the following value for the parameter:

has_attached_file :image,
  ...
  :convert_options => { :all => '-strip -colorspace RGB -resample 72'}
  ...

The list of supported parameters can be found here Below is the description of those that I use.

“-strip” tells IM to strip the image of any profiles or comments, which you probably don’t need and which helps to reduce the size of the image.
“-colorspace RGB” obviously sets the image colorspace to RGB. It’s more a specific of projects that I work on, where users sometimes upload CMYK images that are BTW not supported by some browsers (like, you know, IE).
“-resample 72” resamples the image to 72dpi resolution. Again, applications that I work on sometimes get 300dpi images, that need to be converted.

I use these for all attached images, so it can be DRYed by setting it as a default parameter in say config/initializers/paperclip.rb:

Paperclip::Attachment.default_options[:convert_options] = { :all => '-strip -colorspace RGB -resample 72'}

Delete Attachments

Another thing that I need for pretty much any attachment is an ability to delete it (if the attachment is optional). I think a good way to do it is to display the attachment on the “edit” page along with a checkbox that if checked removes the attachment. It’s totally doable, you just need to set the attachment to nil if the box is checked by (I guess) adding some logic to your controller, however it would be nice to have this feature out of the box. And that’s what I’ve added to my fork of paperclip

Basically it creates a virtual attribute for every attachment in the model that is named like “image_delete” if you have an “image” attachment. You just need to make sure that it is included in attr_accessible and add a checkbox to your form:

<% if form.object.image? -%>
  <%= image_tag form.object.image.url %>
  <%= form.check_box :image_delete, :label => 'Delete Image' %>
<% end -%>

Rename attachments

Paperclip provides a neat way to customize paths to your files using interpolations. It works great if you use things like “:id” that never change. However if you’re really crazy about the URLs of your images and want to have something more meaningful there (e.g. image title & author’s name like I do in one of my projects) and you update values that interpolations depend on, you need to rename your files as well. Paperclip won’t do it and hence another feature that is present in my fork

It checks whether it needs to rename files on every update and does it if necessary.

Content type and image dimensions validations

It’s a well-known fact that Firefox on Windows does not send correct mime type headers with attachments, that’s why Paperclip can not correctly validate such uploads. There’s a mimetype-fu plugin that can figure out the file’s mime type when it is already in the file system and my fork uses it if it’s installed.

Besides it also provides a way to validate image dimensions that is missing out of the box:

validates_attachment_dimensions :image, :minimum => 300, :maximum => 900

It will check if the image’s smallest side is bigger than the minimum parameter and the largest side is smaller than the maximum.

This seems to be it. Paperclip is a great gem and I like it even more with these tiny tweaks.

Cucumber and Unobtrusive Javascript

2009-09-25T00:00:00+04:00

Rails 3 will no longer pollute views with javascript code, which is cool. Until then we’ve gotta deal with it ourselves. I personally use jQuery and the following simple solution when I need a link that would make an AJAX call or a non-GET request.

I add “method” and “method_form” CSS classes to the links:

# AJAX
link_to 'Delete Item', item_path(item), :class => 'delete'
# Non-GET request (Creates a form and submits it)
link_to 'Delete Item', item_path(item), :class => 'delete_form'

And a JS snippet like this:

// All A tags with class 'get', 'post', 'put' or 'delete' will perform an ajax call
$('a.get').live('click', function(event) {
  event.preventDefault();
  $.get($(this).attr('href'));
}).attr('rel', 'nofollow');

['post', 'put', 'delete'].forEach(function(method) {
  $('a.' + method).live('click', function(event) {
    event.preventDefault();
    var self = $(this);
    var auth_token = typeof(AUTH_TOKEN) == "undefined" ? '' : AUTH_TOKEN;
    $.ajax({
      data    : '_method=' + method + '&authenticity_token=' + encodeURIComponent(auth_token),
      success : function() { self.trigger('targetedAjaxSuccess') },
      type    : 'POST',
      url     : this.href
    })
  }).attr('rel', 'nofollow');
});

// All A tags with class 'get_form', 'post_form', 'put_form' or 'delete_form' will create a form and submit it
['get', 'post', 'put', 'delete'].forEach(function(method) {
  $('a.' + method + '_form').live('click', function(event) {
    event.preventDefault();
    var auth_token = typeof(AUTH_TOKEN) == "undefined" ? '' : AUTH_TOKEN;
    var form = $('<form/>').attr({action: this.href, method: method == 'get' ? 'get' : 'post'})
    form.append($('<input/>').attr({type: hidden, name: '_method'}).val(method))
    form.append($('<input/>').attr({type: hidden, name: 'authenticity_token'}).val(auth_token))
    $(document.body).append(form)
    form.submit()
  }).attr('rel', 'nofollow');
});

The JS snippet finds all links with the CSS classes and either makes an AJAX call or creates a hidden form and submits it when someone clicks on them.

This works fine, but when it comes to Cucumber and Webrat, they don’t care about those classes and just make a GET request when I ask to follow such link. My first solution for fixing it was to modify the default “When I follow …” Cucumber step to find the link first, check if it has a CSS class and use a proper HTTP method if it does, like this:

When /^I follow "([^\"]*)"$/ do |link|
  link = webrat.current_scope.find_link(link)
  method = /(post|put|delete)/.match(link.element.attributes['class']).to_a.last
  link.click(:method => method)
end

Webrat proxies some methods (like click_link, visit, fill_in, etc) to webrat.current_scope. So that’s the object you need if you’d like to call other methods (like find_link in this case). The find_link method returns a Webrat::Link object that in turn has a Nokogiri element object (link.element), so that’s how you can get its HTML attributes.

Alright, it works. But wait, Webrat can actually handle inline JS that is generated by default Rails helpers, right? So changing that bit of code to use CSS classes would work for unobtrusive JS as well. And we won’t have to change the default Cucumber steps every time we update Cucumber. It appears that Webrat does it in Webrat::Link::http_method:

def http_method
  if !onclick.blank? && onclick.include?("f.submit()")
    http_method_from_js_form
  else
    :get
  end
end

If we override this method to look something like this (drop the following to your features/support/env.rb after Webrat is included):

module Webrat
  class Link

  protected

    def css_class
      Webrat::XML.attribute(@element, "class")
    end

    def http_method_from_css_class
      /(post|put|delete)/.match(css_class).to_a.last
    end

    def http_method
      http_method_from_css_class || :get
    end
  end
end

The standard Cucumber step starts working like we expect it to, using proper HTTP methods for requests.

I’m pretty sure that something like this will be added to Webrat once Rails 3 is released (cause it won’t have inline JS anymore). Until then this snippet can be used.

Shoulda Macros in Cucumber Features

2009-05-22T00:00:00+04:00

It’s a well known fact that one can use cucumber with any testing framework. There are a lot of posts on that, but basically one needs to comment out lines that require rspec in features/support/env.rb and update a couple of step definitions that use rspec in features/step_definitions/webrat_steps.rb

If you use shoulda in particular, it also works just fine, however you’ll notice that you can’t use controller macros in step definitions. Although this is correct in terms of ideology (you should be using them in functional tests instead) and technology (macros are not included in ActionController::Integration::Session which is the context of cucumber step definitions) depending on the way you use Cucumber and write your features, you may want to use them.

First, you’ve got to mix Cucumber and shoulda matchers by adding this line to features/support/env.rb:

World(Shoulda::ActionController::Matchers)

It will make matchers accessible in your step definitions. At this point, if you were using Rspec you could relax, cause the following step definition would work perfectly:

Then /^the "(.*)" layout should be used$/ do |layout|
  @controller.should render_with_layout(layout)
end

But since you’re a shoulda addict, read on.

Shoulda macros are supposed to be class methods of Test::Unit::TestCase and they obviously won’t work as instance methods of ActionController::Integration::Session. But if you take a peek at the sources of standard macros, you’ll notice that they use matchers (which makes sense to avoid duplication) internally.

Besides matchers and macros shoulda adds a bunch of assertions to your tests. One of them is assert_accepts, that takes a matcher and an object that’s being tested and asserts that the object meets the matcher requirements. Exactly this assertion is used in the standard shoulda macros and you can use it as well in your step definitions:

Then /^the "(.*)" layout should be used$/ do |layout|
  assert_accepts render_with_layout(layout), @controller
end

And that’s it. You’ve got access to shoulda matchers in your cucumber step definitions without rspec, which is basically the same as using macros.

Now one could argue that you should not test which layout is rendered in your acceptance tests. And personally I don’t. But as I mentioned above, it depends on the way you use cucumber. It’s just a tool and there many ways it could be used. I would say that if it makes you productive and your software more robust and maintainable, you’re doing it right.

Ruby Group Meeting in SPB. Как это было и зачем

2009-05-05T00:00:00+04:00

26 апреля в Питере в iClub прошло собрание любителей Ruby. Это было второе мероприятие в рамках railsclub.ru, поэтому информация о нем и материалы есть на официальном сайте. Для меня это был первый опыт орагнизации встречи и публичного выступления. Было довольно интересно и я надеюсь мы будем собираться регулярно. Меня несколько раз спрашивали о том, зачем вообще нужны эти встречи, кто может в них участвовать и т.д. Я хочу поделиться своими мыслями на этот счет с надеждой привлечь больше людей на будующие встречи, а так же сделать их лучше.

О чем рассказать на такой встрече

Все, чем Вы занимаетесь, что более-менее необычно, может быть интересно другим.

У Вас есть какая-то open source (или которой можно поделиться) наработка для решения какой-то задачи.
Есть проект, над которым Вы работаете и решили какие-то проблемы определенным образом (организация кода, процесса, производительность…).
Вы Начали использовать какой-то новый подход или инструмент и он Вам нравится.

Стоит только спросить — интересно ли это кому-то и почти наверняка найдутся интересующиеся.

Зачем выступать

Цели, которые можно достичь напрямую

Привлечь разработчиков к своему open source проекту

Чтобы их привлечь нужно показать, что проект полезный и интересный. Выступление с демонстрацией основных фишек — отличный способ это сделать.

Заинтересовать (напрямую или косвенно) своим коммерческим продуктом

Продукт может быть любым — как непосредственно для аудитории, так и для всех. Можно рассказать о продукте, который Вы разрабатываете, об особенностях, технических задачах, которые пришлось решить и тем самым привлечь внимание. Либо косвенно упомянуть о продукте в контексте выступления.

Найти работников или работу

Невозможно получить полное представление о потенциальной работе по объявлению, одному разговору с менеджером по персоналу, директором и т.д. Так же невозможно понять подходит ли потенциальный работник, задав несколько шаблонных вопросов (почему Вы хотите работать в нашей компании? — Я понятия не имею — разослал резюме в миллиард мест) и получив на них такие же шаблонные ответы. Есть возможность узнать больше о компании или работнику по блогу, open source проектам и т.д. Но я думаю общение в неформальной и не связанной с рекрутингом обстановке может сказать даже больше. Выступление для компании — возможность рассказать о себе перед целевой аудиторией в контексте какого-то проекта например. Для разработчика — возможность выступить перед потенциальными работодателями или коллегами.

Найти единомышленников для работы над проектом

На одном из подобных собраний появился github

Сформировать бренд или реализовать амбиции (В хорошем смысле, если он вообще есть)

Jay Fields об этом написал явно лучше меня.

Цели, которые можно решить косвенно

Хорошо изучить предмет, о котором Вы будете рассказывать

Я узнал довольно много о cucumber и связанных вещах, когда готовился к выступлению.

По-новому посмотреть на инструмент (процесс, решение, и т.д.), который Вы используете

Раза 2 я поменял свое отношение к тому, как я пишу cucumber features. В какой-то момент задумался о том, нужно ли мне их вообще писать. Это произошло, потому что я попытался найти как можно больше материалов по теме от разных людей.

Взглянуть на продукт (библиотеку, и т.д.) со стороны человека, который о нем ничего не знает

Это очень полезно, когда Вы рассказываете о чем-то своем. Разработчику очень тяжело отвлечься и посмотреть на результат своей деятельности глазами пользователя. А это невероятно важно.

Научиться доступно излагать свои мысли и выступать публично

Думаю это полезно всем и каждому.

Глобальные цели

Привлечение новых людей в сообщество
Обучение начинающих

Новые люди — новые взгляды и новые проекты.

Зачем это мне?

Для меня это интересный опыт, возможность пообщаться (я работаю дома один) и удовлетворение от безкорыстно совершенного поступка.

Зачем приходить

Многое можно найти в Интернете и прочитать (и многие так и делают, когда перед ними встает проблема или задача). Зачем тогда приходить?

Организованное обучение (Не нужно искать, выбирать время, настраиваться и т.д.)
Можно влиять на процесс изложения (в своих интересах) — задавать вопросы
Встретить людей, решающих те же проблемы что и Вы
Пообщаться и интересно провести время

Как рассказывать

Коротко. На следующей встрече мы постараемся ограничится 15-20 минутами на выступление

Мои 40 минут были явно перебором.

Конкретная и специфическая тема лучше чем общая и пространная

Я набрал себе кучу тем и в итоге только поверхностно по ним прошелся. Лучше полноценно рассказать о чем-то небольшом.

Хорошо показывать на конкретном реальном примере

Маленькое конкретное приложение лучше, чем словесное описание абстрактной проблемы.

Кодинг в живую — это вероятно лучший способ, но это нужно уметь делать

Я думаю все видели хорошие и плохие скринкасты. В плохих автор неуклюже мечется туда-сюда, опечатывается, а потом пытается разобраться почему ничего не работает. Это отвлекает от темы. Я не умею писать код в живую, поэтому написал весь код заранее.

Лучше подготовить все заранее, чтобы не тупить во время выступления

На выступлении я по сути первый раз пользовался маком. Как сделать шрифт крупнее? Куда ставятся gems? На эти вопросы не должны отвечать те, кто пришел послушать мое выступление.

Код должен быть хорошо виден

Иначе смысла нет его показывать. Настраивайте размер шрифта заранее.

SSH without password

2009-03-30T00:00:00+04:00

I don’t mean to break new ground here, but for one or another reason it took me a while a couple of times to figure out why it didn’t work. There’s a huge amount of posts out there that describe how to setup SSHing to your server without a password, which have different sets of steps to make it work. This one seems to work for me (figured by trial and error):

On your server you need to make sure that ~/.ssh dir exists. Then make sure that the permissions are correct:

$ chmod go-w ~/
$ chmod 700 ~/.ssh
$ chmod 600 ~/.ssh/authorized_keys

Then you need to generate an RSA key unless you already have it:

$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/user/.ssh/id_rsa): 
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /home/user/.ssh/id_rsa.
Your public key has been saved in /home/user/.ssh/id_rsa.pub.

So now you have the key generated in ~/.ssh/id_rsa, and the filnal step is to copy the generated key to the server. I use Ubuntu and do it this way:

ssh-copy-id -i ~/.ssh/id_rsa.pub username@host

At this point you should be all set. Try to ssh to the server and it won’t prompt for a password.

Update: There’s a really neat feature (thanks, Dan) that let’s you create ssh aliases, so you could do “ssh production” instead of “ssh user@production.host.com”. Aliases can be specified in ~/.ssh/config like this:

$ cat /home/eugene/.ssh/config 
Host production
HostName production.host.com
User user

Host staging
HostName staging.host.com
User user

This is a nice addition to the ablility to ssh without passwords.

Deploying a jekyll generated site

2009-03-26T00:00:00+03:00

Ok, so I’ve finally migrated this blog from mephisto to jekyll and just want to share a couple of gotchas.

The migration itself went pretty well. I’ve used scripts posted here to dump posts (although then I noticed that there’s a mephisto converter in jekyll itself that is not mentioned in the README) and move comments to disqus.

There was one thing with URLs though. I’m using “pretty” permalink style which generates directories for each post and puts an index.html with the post itself there (like /2009/3/26/deploying-a-jekyll-generated-site/index.html) so you could have URLs without “.html” at the end (/2009/3/26/deploying-a-jekyll-generated-site/), cause I had this type of URLs in mephisto. Now apache redirects you to “/url/” if you type “/url” in this case. And for disqus “/url” and “/url/” are two different URLs and if you dumped comments with URLs without the trailing slash, they won’t be displayed. This issue with pretty URLs is now fixed.

Then another thing was how to deploy the site. I’m hosting this on a shared dreamhost account and thus it would be difficult to generate the site on the server. It doesn’t have pygments (which is used for syntax highlighting) and I was using the edge version of jekyll.

So I added the generated site (“_site” dir) to the git repo, created a clone of the repo on dreamhost, pointed the domain to the “_site” dir and added a post-update hook to the remote repo (hosted on the same account) which does “git pull” on dreamhost after every “git push” on my end:

$ cat ~/git/blog.git/hooks/post-update 
#!/bin/sh
unset GIT_DIR && cd /home/eugenebolshakov/blog/ && git pull

The important thing here is “unset GIT_DIR”. post-update is called by receive-pack that sets GIT_DIR to ‘.’ and confuses “git pull”. I’ve found the hint here.

Now I can just add a post, generate the site ( ~~I have a shortcut script for that in the repo with the params I use~~ _config.yml works great for that), do git push and I’m all set. Nice!

Hoptoad as an online application events log

2008-10-19T00:00:00+04:00

Now everyone’s familiar with Hoptoad, right? It’s “cool”, “slick”, “essential” and is “your friend” when it comes to collecting and analyzing errors in your Rails application.

“When an uncaught exception occurs, HoptoadNotifier will POST the relevant data to the Hoptoad server specified in your environment.” But besides that it can also store any kind of information you want. That’s what the documentation says:

1 #If you want to log arbitrary things which you've rescued yourself from a
2 #controller, you can do something like this:
3 
4 rescue => ex
5   notify_hoptoad(ex)
6   flash[:failure] = 'Encryptions could not be rerouted, try again.'
7 end

What it does not say (but the comments in the sources do) is that you can also pass a hash to notify_hoptoad method and store whatever you want, not just an exception. And you can also use it anywhere, not just in controllers.

Now let’s assume you have an online store that uses some sort of third party API to calculate shipping costs. That API like any other thing you have no control over can unpredictably go down from time to time. In that case you don’t want to display an error page, but instead use some predefined shipping rate and let the customer complete his purchase. But still you want to be aware of that say to analyze how stable the API is and maybe start looking for something else if it goes down too often.

So inside your code where you make a call to the API you can notify Hoptoad when it goes down like this:

 1 begin
 2   params = {
 3     :quantity => total_quantity,
 4     :weight   => total_weight,
 5     :country  => country,
 6     :postcode => postcode    
 7   }
 8   self.shipping_rates = ShippingCalculator.new(params).shipping_rates 
 9 rescue => e
10   HoptoadNotifier.notify(
11     :error_class   => "Shipping Calculator Error",
12     :error_message => "Shipping Calculator Error: #{e.message}",
13     :request       => {:params => params}
14   )
15   self.shipping_rates = [default_shipping_rate] 
16 end

While in your controllers you can use the “notify_hoptoad” method which is mixed in when the plugin is loaded, anywhere else in your code HoptoadNotifier.notify can be used that like the “notify_hoptoad” accepts either an exception or a hash. It’s all clear with an exception – Hoptoad will get all the information about the error itself. As for a hash, this are the keys you should pass:

:error_class – Use this to group similar errors together. Apparently when Hoptoad catches an exception it sends the class name of that exception object.
:error_message – This is the title of the error you see in the errors list. For exceptions it is “#{exception.class.name}: #{exception.message}”
:request – While there are several ways to send additional data to Hoptoad, I’ve found passing a Hash with :params key as :request suitable for the situation described above. Apparently when Hoptoad catches an exception in a controller the actual HTTP client request is being sent using this key.

Hoptoad merges the hash you pass with these default options:

 1 def default_notice_options #:nodoc:
 2   {
 3     :api_key       => HoptoadNotifier.api_key,
 4     :error_message => 'Notification',
 5     :backtrace     => caller,
 6     :request       => {},
 7     :session       => {},
 8     :environment   => ENV.to_hash
 9   }
10 end

As you can see there are several other parameters you can set / override.

So at the end of the day I have a store that allows people to buy stuff no matter what happens to the Shipping API I use and at the same time I keep track of problems that occur in the background using a nice and friendly web interface

Poking in ActionController

2007-10-30T00:00:00+03:00

I have an ‘accept’ action in one of the controllers and when I was trying to run a functional test against it I got:

ActionController::UnknownAction in 'ContributorRequestsController for moderator allow to accept a request'
No action responded to accept

And of course it worked fine when I’ve actually started the server and invoked it from browser.

I’ve realized that the reason probably was some name clashing or something, but it only appeared in the tests. So I’ve decided to have some debugging fun and I think the outcome is the case when code extracts speak louder than words:

ActionController::Base:

def perform_action
  if self.class.action_methods.include?(action_name) 
    ...
  else
    raise UnknownAction, "No action responded to #{action_name}", caller
  end
end

def self.action_methods
  @action_methods ||= Set.new(public_instance_methods - hidden_actions)
end

def hidden_actions
  write_inheritable_attribute(:hidden_actions, ActionController::Base.public_instance_methods) unless read_inheritable_attribute(:hidden_actions)
  read_inheritable_attribute(:hidden_actions)
end

If your action is named as one of the ActionController::Base.public_instance_methods then it won’t be invoked. While that’s reasonable, I wondered what that reserved ‘accept’ method did. I’ve failed to find it in the rails and rspec sources and finally simply did a search for ‘def accept’ against the project and found it in lib/authenticated_test_helper.rb which is generated by acts_as_authenticated plugin.

def accept(accept)
  @request.env["HTTP_ACCEPT"] = accept
end

NetBeans + BEA JRockit

2007-10-01T00:00:00+04:00

NetBeans Ryby IDE was cool. On my PC at work. But when I’ve got a new laptop and switched to working on it, it appeared to be dead slow when editing RHTML files. I’ve tried to figure out the reason (tried different builds, settings, etc…) and finally realized that I’ve had BEA JRockit JVM on my PC and SUN JVM on the laptop. So I’ve installed JRockit and now it seems to work great again.

So the moral is that NetBeans appears to work faster on AMD64x2/Ubuntu laptop with BEA JRockit. Perhaps not just for me…

Перевод серии статей про REST on Rails

2007-08-31T00:00:00+04:00

Когда я искал инфу о REST, то нашел на мой взгляд хороший туториал (101) из 5-ти частей, автором которого является Jeff Cohen. Сам автор предложил опубликовать ссылки на переводы туториала на другие языки и я решил попробовать перевести его на русский. Я далеко не переводчик, и не филолог/лингвист, поэтому перевод наверняка изобилует разнообразными ошибками. Если есть желание принять участие в редактировании – пишите. И конечно, всегда лучше читать подобные вещи в оригинале (там с картинками и прибаутками), но тем не менее вот:

P.S. Большое спасибо Антону (aka Tonic) за помощь с переводом.

REST Ликбез. Часть 5. Ответ.

2007-08-31T00:00:00+04:00

Перевод (подробности здесь) статьи REST 101: Part 5 – Respond!, автором которой является Jeff Cohen.

В предыдущей статье мы узнали, как Rails позволяет обращаться к ресурсам средствами HTML. Но наше приложение будет использоваться не только с помощью обычных HTML браузеров, но и с сотовых телефонов, а так же другими приложениями через API.

С 1-ой по 4-ую статьи мы знакомились с основами концепции REST и к текущему моменту все точки расставлены. Осталось соединить их линиями, чтобы увидеть картину целиком. Это моя любимая часть, в том числе потому, что в ней рассмотрена реализация REST в Rails, являющаяся еще одним примером того, насколько прекрасен Ruby.

Коротко, но так… мило

Для того чтобы наше REST приложение заработало, нужно заставить контроллер правильно отвечать на запросы в зависимости от того, кто находится на другом конце провода и отправляет их. В качестве простого примера можно рассмотреть получение списка аэропортов. Если Вы воспользовались генератором scaffold_resource, то у Вас должен был получиться примерно такой код:

    class AirportsController < ApplicationController

        def index
            @airports = Airport.find :all

            respond_to do |format|
                format.html  # do nothing, allow Rails to render index.rhtml
                format.js    # do nothing, allow Rails to render index.rjs
                format.xml   { render :xml => @airports.to_xml }
            end
        end

    end

Первая строка метода понятна – получаем все аэропорты. Но остальной код выглядит несколько необычно. Все что он делает – это отображает список аэропортов в HTML, XML и даже с использованием AJAX, если это потребуется. Для того, чтобы понять, как это работает нужно познакомиться с respond_to.

HTTP клиенты могут добавить различную мета-информацию к своему запросу в виде HTTP заголовков. Заголовок – это просто необязательная пара ключ-значение. Существует несколько определенных стандартом заголовков, которые могут быть использованы. например заголовок “Accept-Type”. В качестве значения этого заголовка клиент может передать формат, в котором он способен прочитать ответ. В качестве значения может выступать любой из MIME types, но если значение этого заголовка не указано, то сервер считает что клиент способен адекватно воспринять HTML. Таким образом, если клиент посылает заголовок “Accept-Type: text/xml”, то предполагается что сервер вернет ответ в виде XML документа.

Именно заголовок Accept-Type вызывает магические действия внутри блока resond_to. Вот плохой пример того, как можно было бы реализовать поддержку различных форматов (предположим что Rails передает значение заголовка Accept-Type в наш метод):

    class AirportsController < ApplicationController

        # Pretend that Rails will call our index action, 
            # and will pass in the value of the Accept-Type header
        def index(client_format)
            @airports = Airport.find :all

            if client_format == "text/html"
                # TO DO: render the default template

            elsif client_format == "application/javascript"
                # TO DO: return some javascript

            elsif client_format == "application/xml" || client_format == "text/xml"
                # TO DO: return some XML back the client

            # ... more elsif statements here for each MIME type you want to support
            end
        end

    end

Но это некрасиво

Если закрыть глаза на уродство, то будет видно что сам по себе алгоритм очень прост – в зависимости от запрашиваемого формата отображаем список аэропортов тем или иным образом. Я легко могу себе представить, как команда разработчиков Rails стартовала с подобного кода (хотя бы в голове), но быстро решила просто добавить хэлпер respond_to, чтобы избежать безобразия:

 respond_to do |format|
    format.html  # do nothing, allow Rails to render index.rhtml
    format.js    # do nothing, allow Rails to render index.rjs
    format.xml   { render :xml => @airports.to_xml }
  end

Мы можем не знать, как устроен метод respond_to, но мы точно знаем, что он принимает Ruby блок. (Если Вы не знакомы с блоками в Ruby, попробуйте немного погуглить и возвращайтесь обратно). Внутри блока Вы получаете в свое распоряжение объект, который я назвал format и вызываете три метода этого объекта.

Идея состоит в том, что Rails не может догадаться, какие типы клиентов Вы хотите поддерживать, но может сделать 80% черной работы за Вас. Необходимо только указать типы клиентов, которые Вас интересуют, и отобразить ресурс в виде, понятном клиенту. Вместо того, чтобы говорить Вам какой формат ответа запрашивается, Rails просит Вас указать, какие форматы Вы готовы поддерживать. И для каждого формата (если захотите) можно указать блок кода, который непосредственно отобразит ресурс.

В приведенном выше примере мы говорим Rails, что для клиентов, запрашивающих HTML и Javascript можно выполнить действие по умолчанию – отобразить шаблон в соответствующем формате, но если клиент хочет получить XML, необходимо выполнить указанный нами блок кода.

Помните, как когда-то очень давно мы говорили о разнице между ресурсом и множеством различных его представлений? О том, что HTML – это на самом деле всего лишь одно из возможных представлений (Ваше приложение это не WEB страница и т.д.)? Теперь это видно даже в коде – HTML всего лишь один из вариантов.

Что дальше?

Понятно, что невозможно охватить все, что связано с REST в нескольких статьях. Именно поэтому серия и называется “ликбез”. Но мы поговорили о многом, в том числе и о том, как проектировать приложения согласно REST, о концепции ресурсов и о том, как это отличается от традиционного ООП подхода.

Думаете о том, что же делать дальше? Просто попробуйте! Создайте REST приложение с нуля, воспользуйтесь генератором scaffold_resource, изучите сгенерированный код, попробуйте подредактировать views и контроллеры. Это легче чем Вы думаете.

Вот некотрые источники, которые я могу порекомендовать для более подробного изучения (обратите внимание, PeepCode поддерживает блог автора)

PeepCode скринкаст о REST
Выступление DHH’s на RailsConf 2006 и запись в его блоге
Держите руку на пульсе Edge Rails вместе с Ryan Daigle

Можете посоветовать что-то еще? Оставляйте ссылки в комментариях.

Rails + Windows Command Line Tips

2007-08-16T00:00:00+04:00

We do lot’s of things from console when using Rails and it can be a little painful on Windows. However, we can try to make our lives better.

To begin with, I must confess in being a great lamer. I always used Windows (Update: Finally on Ubuntu!) (except some crazy attempts including a night session of trying to run MacOSx86 on VmWare, qemu and kqemu under Linux on a processor that doesn’t support SSE2), never used things like Far manager (the tool used by all crazy Windows guys, well, at least in Russia), never wrote bat files (except the ones in the University that were considered to be viruses by AVP for some reason), never managed to remember all those tricky keyboard shortcuts, nothing.

But once started to use Rails I began to love The Console. Really, lot’s of things can be done easier and faster. But there are several things I don’t like about the Windows console (cmd.exe).

First of all, I use gems documentation a lot. The one that can be accessed from the browser on the 8808 port (by default) when you run gem_server. It’s cool. The only thing I hated about it is that I had to run it every day and that its console window was hanging about the desktop. So I’ve found a nice tool called Hidden Start that allows to run console applications in the background without any windows. So I’ve simply added it to the Startup folder and now I can access RDoc gems documentation instantly!

The next thing I do very often is starting the console session to run tests, rake tasks or other things against my Rails application. The thing I hated is that I had to change the current directory (home directory that is opened by default when one starts cmd.exe) to the directory of the application, which always took a while cause I’ve had to change the drive and type the long path to the application. I wanted just to open a console and type a command without changing the directory. It appeared that one can change the default cmd directory by hacking the registry, but I didn’t want that cause I have several applications that I want to use console with. So I created a shortcut for cmd that opens the console window and sets the current directory (I’ve found the parameters somewhere on the net):

%windir%\system32\cmd.exe /k "cd /d d:\really_long_path_to_my_rails_project"

The last thing is the Rails Application Server. I currently use Mongrel, but it doesn’t really matter. Every day I had to open the console window, change the directory (Shit! Again!) and run ruby script/console, which I also hated of course. This time a simple bat file saved my hair (at least for a while):

cd /d d:/really_long_path_to_my_rails_project
ruby script/server

I’ve added the above mentioned 2 files to my quick launch panel and now I feel happier! But as stated, I’m a lamer, so I’ll be grateful to hear ideas on how to make it better.

Update: In love with Ubuntu for more than a year now

REST Ликбез. Часть 4. Маршрутизация.

2007-08-08T00:00:00+04:00

Перевод (подробности здесь) статьи REST 101: Part 4 – Routing, автором которой является Jeff Cohen.

Ранее мы выяснили, что проектирование системы согласно REST начинается с выявления ключевых ресурсов. Сегодня нам предстоит узнать, как Rails обрабатывает REST запросы, и каким образом Ваш код должен на них реагировать.

Я также хочу немного отойти в сторону и напомнить, что REST – это технология, применяемая не только в Rails. REST изобрели гораздо раньше, и это подход, который можно использовать при разработке различных программ вне зависимости от используемых инструментов. Теперь, когда я знаком с REST, я скорее всего не буду писать WinForms приложения так, как я делал это раньше.

Ресурс == Контроллер

Вы уже знакомы с моделями и контроллерами. Но как реализовать REST приложение с их помощью? В первую очередь нужно усвоить несколько вещей:

Ресурс не всегда соответствует модели Rails или таблице в базе данных. Иногда ресурс является “виртуальным” и существует только в описании бизнес модели и логике приложения, но не связан с таблицей в базе.
Тем не менее ресурс всегда связан с контроллером.
Любители (такие как я) абстрактных интерфейсов могут считать класс-контроллер реализацией интерфейса REST.
Контроллер реализует ресурс вне зависимости от того, какой клиент к нему обращается (HTML браузер, XML клиент, RSS парсер, и т.д.), и таким образом, ему необходимо отправлять ответ в том формате, в котром его ожидает клиент. В 3-ей части я описывал, что нам необходимо реализовать поддержку нескольких типов клиентов (WEB, мобильный телефон, RICH клиент и т.д.) для одних и тех же ресурсов. Один контроллер реализует отображение данных ресурса независимо от формата запроса.

Семь

Большинство ресурсов запрашиваются индивидуально (аэропорт), либо в виде коллекции (список аэропортов). Ваш контроллер будет реализовывать следующие семь действий (методов).

Четыре этих:

show : обрабатывает GET запрос для отображения индивидуального ресурса
create : обрабатывает POST запрос для создания нового экземпляра ресурса
update : обрабатывает PUT запрос для обновления существующего экземпляра ресурса
destroy : обрабатывает запрос DELETE для удаления экземпляра ресурса

И три этих:

index : обрабатывает GET запрос для отображения коллекции ресурсов
new : обрабатывает GET запрос для получения пустой формы для добавления экземпляра. Как правило используется HTML клиентами
edit : обрабатывает GET запрос для получения формы, заполненной данными текущего ресурса, опять же, как правило используется HTML клиентами.

Названия этих методов имеют большое значение, потому что Rails будет перенаправлять запросы методам с именно такими именами.

Разумеется, необязательно реализовать все семь методов. Если бизнес модель подразумевает что один из ресурсов предназначен только для чтения, то разумно реализовать для него только методы index и show.

Вы наверное уже с ужасом думаете о том, как создавать полноценные Rails приложения, учитывая что в Вашем распоряжении только эти семь методов. Первым делом, не беспокойтесь. Если вы на действительно уверены в том, что в Вашей ситуации необходимо ввести еще несколько дополнительных методов, то добавляйте. Но знайте, что это может быть признаком того, что Вы не достаточно хорошо подумали архитектуру приложения и возможно определили не все ресурсы.

Регулировщик

Теперь нам нужно понять, как сопоставить URL и HTTP запросы с методами нашего контроллера.

Обычно название метода, который будет вызван видно в URL. Надеюсь вы помните, как работает стандартный механизм Routing в Rails. Если нет, то вот 5-ти секундный курс, который освежит Вашу память: файл routes.rb содержит правила сопоставления URL с контроллерами и их методами:

map.connect '/airports/:action/:id', :controller => 'airports'

В этом примере URL www.mydomain.comm/airports/open/45 сопоставляется с контроллером (классом) AirportsController и его методом open. В момент вызова метода open, params[:id] будет содержать число 45.

Но для того чтобы реализовать REST подход, нужно поступить по-другому. В первую очередь, один и тот же URL может в зависимости от типа HTTP запроса соответствовать разным методам, например URL

/airports/1

должен вызывать метод show (для отображения аэропорта №1) если был использован запрос GET, но в случае запроса DELETE должен вызывать метод destroy.

Раньше в Rails не было возможности определить такие правила с помощью map.connect, но с приходом версии 1.2 появилась одна маленькая, но очень важная фича, суть которой непонятна тем, кто незнаком с REST:

map.resources 'airports'

Выглядит очень коротко, но в то же время очень многое значит, а именно:

у вас есть ресурс airports (обратите внимание на множественное число, это важно)
Вы хотите чтобы Rails использовал REST соглашения для сопоставления запросов
маршрутизация запросов будет происходить не только основываясь на URL, но и с учетом типа HTTP запроса
все запросы, связанные с ресурсом airports должны направляться контроллеру AirportsController (заметьте, опять множественное число)
все URL для этого ресурса будут соответствовать REST соглашениям (об этом чуть позже)
в Вашем распоряжении будет набор предопределенных именованных URL для каждого действия над этим ресурсом

Пара URL/тип HTTP запроса будет автоматически сопоставлена методам контроллера вот так:

/airports/ + POST = create
/airports/1 + GET = show
/airports/1 + PUT = update
/airports/1 + DELETE = destroy
/airports/ + GET = index
/airports/new + GET = new
/airports/1;edit + GET = edit

Замечание. Точка с запятой, которая наверняка бросилась в глаза в URL для метода edit является стандартом в Rails 1.2.3, но будет заменена на слэш в Rails 2.0.

Все что Вам осталось сделать, это реализовать семь методов в Вашем контроллере. Остальное за Вас сделает Rails!

Это еще не все

Но это еще не все. В Rails 1.2 появился очень изящный генератор scaffold_resource, который способен создать все необходимое для Вашего нового ресурса: код в routes.rb, контроллер со всеми семью методами, RHTML шаблоны для этих методов и миграцию для создания соответствующей таблицы в базе данных, т.е. все что необходимо для начала.

И действительно, самое полезное из того что Вы можете сделать для изучения REST – это создать новое приложение и сгенерировать ресурс. Создайте базы данных myapp_development и myapp_test, и наберите вот эти команды:

c:\dev> rails myapp
c:\dev> cd myapp
c:\dev\myapp> ruby script/generate scaffold_resource airport name:string designator:string
c:\dev\myapp> rake db:migrate

Потом запустите сервер ruby script/server и наберите в браузере localhost:3000/airports. Теперь Вы можете создавать, редактировать и удалять аэропорты, но как все это работает?

Просто загляните в airport_controller.rb – весь код находится там, и его на удивление мало. Просмотрите его, потому что для того чтобы продолжить, необходимо чтобы Вы понимали, что там происходит.

Потом, посмотрите на rhtml шаблоны и обратите внимание на то, как в них используются сгенерированные именованные URL, чтобы понять, каким образом входящий запрос связывается с методом контроллера и какой шаблон будет отображен в ответ.

В коде контроллера есть одна конструкция, которую Вы возможно не видели раньше: блок respond_to, который выглядит немного странно. Это очень важная часть реализации REST и мы рассмотрим ее более подробно в следующий раз.

REST Ликбез. Часть 3. Проектирование согласно REST.

2007-08-01T00:00:00+04:00

Перевод (подробности здесь) статьи Rest 101: Part 3 – RESTful Design, автором которой является Jeff Cohen.

Ранее мы обсуждали разницу между WEB-страницей и ресурсом. Сегодня нам предстоит понять как архитектура, основанная на ресурсах, может быть нам полезна.

С текущего момента считайте свое приложение не более чем хранилищем ресурсов. Что такое хранилище? SVN – хороший пример хранилища исходных кодов. MySQL – хранилище реляционных данных. Позиция хоккейной команды Chicago в турнирной таблице NHL – это доступное только для чтения хранилище некоторой хоккейной статистики.

Сейчас мне нужно придумать хранилище ресурсов, которое я буду использовать в качестве примера в этой статье.

Допустим Вы работаете в Softies TransAir и Вам поручили создать программную инфраструктуру компаниии с нуля.

1. Вам необходим инструмент для занесения информации об авиарейсах. Авиарейс – это самолет перемещающийся из одного города в другой в определенное время.
2. Вам необходим WEB интерфейс для сотрудников аэропорта. Вы также хотите, чтобы пассажиры могли проверить статус рейса с мобильного телефоны
3. Ваш начальник хочет, чтобы Вы реализовали XML-API, который мог бы быть использован сторонними разработчиками для реализации обновления данных на тех самых огромных щитах в здании аэропорта.

Интересный проект, не так ли? Помните как ранее мы обсуждали традиционный объектно-ориентированный подход? Согласно ему можно взглянуть на описание задачи и выделить существительные (которые в последствии станут объектами) и глаголы (которые станут методами). Только представьте сколько замечательных паттернов вы могли бы здесь применить! Я знаю, Вам просто не терпится нарисовать огромную UML диаграмму на доске вместе с несколькими диаграммами взаимодействия! И Вы уже видите реализованными методы вроде FlightSchedule.CancelFlight() и Flight.Delay().

Уж простите. Поскольку Вы решили идти дорогой REST, то большая часть архитектуры уже продумана за Вас. По сути все что Вам остается сделать, это определить ресурсы.

И пожалуй я повторю на тот случай если Вы не услышали меня за шуршанием своих маркеров по доске потому что это действительно важно.

Просто определите ресурсы.

В нашем примере я могу сразу выделить несколько ключевых существительных: самолеты, аэропорты и авиарейсы. Возможно со временем появятся еще, но для начала этого достаточно.

Каким образом клиентское приложение будет обращатсья ко всем этим ресурсам? Для это были изобретены URL (Кстати, вы же знаете что означает L в URL?) Идентификатор каждого ресурса построен по простому шаблону. Например:

/airports – список аэропортов
/airplanes – список самолетов
/flights – список авиарейсов

и:

/airports/ord – аэропорт Chicago O’Hare
/airplanes/ZJ3543 – самолет с серйиным номером ZJ3543
/flights/451 – авиарейс #451

Четыре метода

Хорошо, Вы определились с ресурсами. REST в свою очередь предлагает четыре метода (глагола – если проводить параллель с ООП), которые каждый из Ваших ресурсов может имплементировать.

GET. Я хочу получить представление одного из ресурсов в режиме только чтения.
POST. У меня есть новый ресурс который я хочу добавить в хранилище.
PUT. Я хочу обновить ресурс который уже присутствует в хранилище.
DELETE. Я хочу удалить ресурс из хранилища.

Ничего не напоминает? В SVN GET – это команда ‘checkout’ или ‘update’. POST – это команда ‘add’. PUT это команда ‘commit’. ‘DELETE – это собственно команда ’delete’. Если сравнить с MySQL, GET – это запрос SELECT, POST – это INSERT, PUT – это UPDATE и DELETE – снова просто DELETE.

Теперь когда мы определились с ресурсами и методами можно заканчивать проектирование и переходить к реализации.

Вызов методов при помощи HTTP

В WEB-приложениях в качестве средства обмена данными между сервером и клиентом используется HTTP. Теперь мы можем подкорректировать неточное описание того, как работает браузер, данное в первой части. Что же происходит на самом деле когда мы набираем URL в адресной строке? Браузер составляет HTTP запрос для вызова метода GET ресурса, идентифицируемого по URL, который мы ввели.

Вы так же можете вызвать метод POST, но только в том случае, если на странице есть форма (Да, не совсем так, благо есть AJAX, но давайте пока остановимся на этом). Формы могут отправлять данные по определенному URL. Когда вы подтверждаете отправку формы, браузер вызывает метод POST у ресурса, расположенного по URL и передает ему данные, которые являются значениями атрибутов ресурса который он хочет создать или обновить.

К сожалению Вы не можете вызвать PUT или DELETE стандартными средствами HTML. Тем не менее каждый HTTP сервер в мире готов принять вызов этих методов и для того чтобы их вызвать необходимо придумать некий способ показать серверу что Вы пытаетесь обратиться к PUT или DELETE.

Таким образом Вы можете связать свой REST API с типами запросов HTTP, но из-за того что средствами HTML нельзя заставить браузер делать запросы PUT и DELETE, сервер и клиент должны договориться о том, как они они будут эмулировать вызов этих методов.

В этой статье мы завершили проектирование и в следующий раз перейдем непосредственно к написанию кода.

REST Ликбез. Часть 2. Миллионы API.

2007-07-31T00:00:00+04:00

Перевод (подробности здесь) статьи REST 101: Part 2 – A Million APIs, автором которой является Jeff Cohen.

В предыдущей статье я пытался убедить Вас в том, что WEB – это совокупность ресурсов, а не WEB-страниц. Сегодня мы еще на шаг приблизимся к пониманию REST.

Объектно ориентированный подход

Если Вы когда-либо занимались ООП, то скорее всего действовали примерно по такому плану:

Необходимо описать, что будет делать Ваша программа.
Существительные в получившимся описании – это классы.
Глаголы – это методы классов.
Для того чтобы программа решала поставленную задача необходимо, чтобы существительные вызывали методы других существительных.

Звучит разумно, и именно так я программировал долгое время. Такой подход часто называется “RPC”-стилем. Я не совсем понимаю причем здесь “удаленность” (RPC – Remote Procedure Call – Удаленный вызов процедур), но знаю, что это является традиционным способом проектирования объектно-ориентированных программ. Это отличный способ, но WEB работает не так. Почему?

Представьте, что на сейчас 1992 год и 3 крупных компании разработали 3 разных онлайн программных продукта: один для покупки книг, другой для бронирования авиабилетов и третий для просмотра аэрофотографий, сделанных в воздухе над Землей. Каждая из компаний создавала свой продукт используя классический объектно-ориентированный подход, описанный выше. Они так-же предусмотрели возможность использования своих продуктов другими приложениями, реализовав для каждого свой собственный API.

Теперь представьте что Ваша задача – создать инструмент, который использовал бы все эти 3 приложения одновременно.

Вам пришлось бы изучить 3 различных API и я готов поспорить что у Вас были бы элементы пользовательского интерфейса, напрямую взаимодействующие с методами этих API. Но этого звучит логично, так? Как бы еще Вы могли это сделать? К тому же, API всего три и Вы, конечно, знаете несколько хороших книг из которых можно почерпнуть паттерны для того тобы упростить архитектуру (и выглядеть круто в глазах сослуживцев). Но что если бы Вам пришлось иметь дело с миллионами API?

Давайте вновь вспомним о браузере. Когда Вы устанавливаете его на на свой компьютер, он не обладает данными о том, какие сайты Вы собираетесь посещать. Он способен отображать любой сайт который Вы заходите, и более того, с его помощью Вы можете покупать музыку, бронировать авиабилеты и рассматривать свой дом на фотографиях из космоса.

Это магия? Задумайтесь над тем, как обстояло бы дело, если бы у каждого сайта был свой API. Для того чтобы купить книгу на Amazon браузеру необходимо было бы уметь вызывать Amazon.Buy(), а когда я нажимал бы кнопку “Просмотреть список авиарейсов”, обращаться к UnitedAirlines.CheckFlights(). Совершенно невозможно создать инструмент, котрый бы использовал миллионы различных API.

Именно поэтому WEB не основывается на RPC. В основе архитектуры WEB лежат ресурсы, т.е. REST.

Согласно Wikipedia, REST – это Representational State Transfer. Чтобы это не значило, смысл в том, что вместо существительных со своим определенным набором глаголов, каждое существительное (с текущего момента будем называть их ресурсами) обладает одним и тем же конечным набором глаголов (т.е. конечный список действий, которые над ними можно произвести). Другими словами у всех ресурсов единый API. Основные методы API позволяют любому клиенту:

Получить ресурс только для чтения.
Создать новый ресурс.
Обновить существующий ресурс.
Удалить ресурс.

Но постойте! Каким из этих методов я смогу “купить книгу”? Каким “найти авиарейсы из Чикаго в Нью-Йорк в следующий вторник”? Каким изменить масштаб карты с уровня “города” до уровня “улицы”? Какой из этих методов позволит посетителю авторизироваться на сайте?

На эти вопросы мы ответим в следующий раз. Но я думаю, что, возможно, у Вас уже есть ответы, если вы действительно перестали думать о “покупке книги” как о WEB-странице и пытаетесь определить какой ресурс используется Вами в этом случае. До встречи.

REST Ликбез. Часть 1. Ресурсы.

2007-07-30T00:00:00+04:00

Перевод (подробности здесь) статьи REST 101: Part 1 – Understanding Resources, автором которой является Jeff Cohen.

Лично мне стоило больших усилий понять, что такое REST. Может быть, потому что большую часть жизни я разрабатывал клиент-серверные приложеня, а не WEB-сайты, или, потому что в момент знакоства с REST я изучал принципы WEB программирования, Ruby, и Rails одновременно. Когда я поехал на первую конференцию, посвященную Rails, там все говорили только о REST, и я, чтобы не казаться придурком, улыбался и делал вид, что в курсе дела, хотя совершенно не понимал о чем речь.

Если Вы, как и я когда-то, пытаетесь понять что же такое REST и как применить эту концепцию в Rails, то эта серия статей для Вас.

Эксперты в HTTP, HTML и REST обязательно будут придираться к тому, насколько я упрощаю терминологию чтобы сфокусироваться на самой теме, но я не желаю этого слышать, потому как эта серия написана не для экспертов :)

Часть 1.

Итак, начнем с самого начала. Как работает браузер? Прежде чем я начал создавать сайты на Rails, я думал что это происходит примерно так:

Я набираю URL в адресной строке, либо нажимаю на ссылку.
Браузер выполняет “HTTP запрос” (чтобы это не значило) и получает HTML в ответ.
Браузер отображает HTML на экране.

Я никогда особо не задумывался о том, как работают, например, формы, а просто считал, что это один из вариантов вышеописанной схемы.

На самом деле, протокол HTTP содержит точные указания о том, как браузер должен отправлять запросы серверу. HTTP принципиально отличается от HTML, который являясь языком разметки предназначен для отображения содержимого страницы. В то время как HTTP помимо банального получения HTML страницы и отправки данных формы позволяет выполнять и другие действия, а именно он поддерживает 8 типов запросов. Наиболее известными являются 2:

Запрос “GET”: используется для получения содержимого какого-либо ресурса в сети. Ресурс обладает уникальным идентификатором – URL.
Запрос “POST”: используется для отправки данных на URL для создания нового ресурса.

Часть 2.

Первым шагом к пониманию REST для меня стало изменение представления о WEB. WEB – это совокупность ресурсов, но не страниц. Я хочу акцентировать на этом внимание и вот почему.

Вчера я отправился на amazon.com и просмотрел несколько товаров, которые мне было бы интересно купить. Еще я прочитал несколько статей из Wikipedia и заголовки свежих новостей на сайте CNN. Потом я познакомился с текущим положением хоккейной команды Чикаго в турнирной таблице NHL.

Чтобы понять REST Вам придется перестать думать обо всех этих вещах как о WEB-страницах. Например, статья в Wikipedia. Это не просто страница, это ресурс (в моем случае – краткая биография Архимеда). Я использовал браузер чтобы получить доступ к этому ресурсу, и он запросил представление ресурса в формате HTML, потому что это та форма, в которой браузеры отображают ресурсы.

Но разве статья про Архимеда не является WEB-страницей? Нет. Я запросил представление ресурса из Wikipedia в формате HTML, ресурса который может быть идентифицирован по URL ”//en.wikipedia.org/wiki/Archimedes”. Wikipedia могла бы отобразить ресурс в любом другом виде – в качестве PDF документа, или возможно JPG изображения, или даже предложить несколько форматов на выбор. Но Firefox отправил GET запрос на получение этого ресурса в формате HTML и ответ был соответствующим.

Другой пример: бронь авиабилета – это ресурс, предоставляемый компанией United Airlines. Они позволяют мне обратиться к этому ресурсу разными способами: как к HTML странице на их сайте, либо они могут отправить информацию о брони в качестве текстового сообщения на мобильный телефон, также они могут отправить мне эту информацию на email, а еще я могу позвонить им по телефону. Один и тот же ресурс, но разные представления.

Надеюсь, теперь это очевидно: моя бронь – не просто WEB-страница. Это реальный ресурс, который может быть отображен при помощи HTML и поэтому я могу воспользоваться браузером и просмотреть информацию о моей брони.

Часть 3.

Теперь, когда я убедил Вас, что WEB – это на самом деле огромное хранилище ресурсов, которые могут быть отображены различными способами, и HTML – это всего лишь один из этих способов, я хотел бы предоставить Вашему вниманию еще одну концепцию. Ресурс – это не обязательно единичный элемент, как, например, биографическая статья или турнирная таблица. Некоторые ресурсы представляют собой совокупность других ресурсов. Ресурсом может быть список праздников, список друзей или несколько постов в блоге.

В следующей статье я собираюсь описать, как HTTP позволяет создавать, читать, обновлять и удалять ресурсы.

Overriding Rake Tasks

2007-07-30T00:00:00+04:00

It seems that I’m lucky cause the project I’m currently working on forces me to deal with non-typical problems again and again. This time I need to override one of the default Rails Rake tasks behaviour. For some reason I thought that I’ll simply be able to do it somehow, but it appeared that Rake doesn’t allow that and I’ve ended up with another plugin :)

I won’t describe why I needed to override Rake tasks right now, I’m going to post another article about it latter, let’s just take it as a matter of course for now.

First of all I’ve tried to simply define a new task with the same name as the existing one and thought that it will work, but Rake adds the new task to the queue in this case and runs both (the new one after the original one).

Then I’ve tried to read more about Rake and found out that one can add “prerequisites” for the tasks (even for exisitng ones) like this:

task :test => ['pre_test_task1', 'pre_test_task2']

While that’s very helpfull, it doesn’t solve my problem. As usual I’ve googled for a solution and found Matthew Bass’s blog post. Actually Mattew described a working solution, but I didn’t like the way it looked. To override a task one have to add the new tasks to the Rakefile like this (we’re overriding Rails “test” task):

remove_task :test
task :test do
  #new task code here
end

I didn’t like the idea of adding new tasks to the Rakefile and the “remove_task” method call before each task. So I’ve spent a couple of hours messing with Rake sources and finally written an “override_task” method that actually deleted existing task with the given name and defined a new one. It can be used like this:

override_task :test do
  #new task code here
end

You can put this in you app’s lib/tasks as usual, or add it to one of your plugins’ tasks. It works with a namespace too of course:

namespace :db do
  override_task :migrate do
    #new migration code here 
  end
end

Then, I thought if it could be made as a plugin. In order to make it work, the code written should be loaded before the tasks and it means that Rakefile should be modified to load it. I’ve recently messed with app_config plugin by Daniel Owsiański and noticed the way it adds a line to environment.rb during installation. I’ve simply copied the idea and the plugin was ready! During installation it adds a line to the Rakefile that loads the plugin itself.

To play with it do the usual

script/plugin install git://github.com/eugenebolshakov/override_rake_task.git

Update: Thanks to Doug for the patch that makes it compatible with Rake 0.8.1+

Rake Task to Display SVN Commits by User

2007-07-26T00:00:00+04:00

At my current job I’m being asked to send a list of trac tickets I’ve been working on in the previous 2 weeks. After reading this post I figured out that it can be easily done with Rake (well, as everything else you can dream about).

Since we’re using an svn hook that adds notes to the related trac tickets on commit, each revision associated with a ticket has its number in the comments. So all I (Rake task) have to do is to collect all my commit commets, pull ticket numbers from them (typical commit comment can look like this: “refs #786”) and display a list, ordered by date.

I didn’t play with command line svn client much previously, but when I’ve started to write the task I’ve figured out that we can get the svn log in xml using the “—xml” option. Even better!

So I’ve ended up with this:

namespace :svn do
  namespace :log do
    desc 'Displays commints by user in the specified period of time. Usage: rake svn:log:by_user USER=username PASSWORD=pass [URL=repo_url] PERIOD=period_option. Where valid period_options: m - current month, 2w - previous 2 working weeks (monday - friday)'
    task :by_user => :environment do
            
      url = ENV['URL'].to_s
      password = ENV['PASSWORD'].to_s
      period = ['m', '2w'].include?(ENV['PERIOD']) ? ENV['PERIOD'] : '2w'
      #USER parameter is mandatory
      raise 'use rake:svn:log:by_user USER=svn_username' unless user = ENV['USER']
      

      case period
        when 'm'
          start_date = Time.now.beginning_of_month.gmtime
          end_date = Time.now.gmtime
        when '2w'
          start_date = (Time.now.beginning_of_week - 2.weeks).gmtime
          end_date = Time.now.beginning_of_week.gmtime
      end

      #datetime format used by svn log
      TF = '%Y-%m-%d %H:%M:%S +0000'
      #we'll use this var to store commits for each day
      days = {}
      
      require 'rexml/document' 
      
      log = REXML::Document.new(`svn log #{url} --xml -r "{#{start_date.strftime(TF)}}:{#{end_date.strftime(TF)}}" --username #{user} --password #{password}`)

      log.root.each_element do |log_entry|

      #save each revision entry to a hash
      revision = {:number => log_entry.attributes['revision']}
      log_entry.each_element { |log_detail| revision[log_detail.name.to_sym] = log_detail.text } 
      
      #is it my revision?
      if revision[:author] == user
        day = Time.parse(revision[:date]).strftime('%y.%m.%d')
        #for each day we want a list of trac tickets affected or revision number
        #trac tickets numbers are included in the comment like this: #687
        #so we'll try to find such numbers using regexp
        #if there are no tickets numbers we'll simply use revision number like this: [1235]
        tickets = revision[:msg].to_s.scan(/#\d+/)
        tickets << "[#{revision[:number]}]" if tickets.empty?
        (days[day] ||= []) << tickets.join(', ')
        end
        
      end
      
      #and we simply output all commits day by day
      days.keys.sort.each do |day|
        puts "#{day} | #{days[day].join(', ')}"
      end
      
    end
  end
end

The task takes 4 parameters: USER (mandatory) – well, obvious, PASSWORD (mandatory), URL (optional) – can be provided if rails app is not a working copy of repository you’d like to get a log from and PERIOD – “m” to use the revisions made in this month only and “2w” (default) to use revisions made in the previous 2 working weeks. So I can run it like this:

rake svn:log:by_user USER=eugene.bolshakov PASSWORD=secret PERIOD=m

and get something like this:

...
07.07.23 | [2256], [2264], [2265]
07.07.24 | #787, #801, #783
07.07.25 | #786, #823
07.07.26 | [2346]
...

The numbers with sharp are ticket numbers and those in square brackets are the revision numbers. They are displayed if the revision is not related to any trac ticket. Yeah, I know it could be done easier with xpath, but my knowledge of it is poor :(

Rake Task to Clear Expired Session Files

2007-07-25T00:00:00+04:00

Perhaps some guys who came to Rails from PHP expected session expiry to be handled automatically. But in Rails we have to deal with it ourselves. There’s an awesome article on the topic. The main idea is that we need to clear expired sessions which were not accessed for some time and the ones which were created a long time ago. I’ve tried to find a ready-made script for this purpose, but found the ones that deal with database based sessions only, so decided to write it myself.

require 'find'

namespace :tmp do
  namespace :sessions do
    desc 'Clear expired sessions'
    task :clear_expired => :environment do
      ctime = (ENV['ctime'] || 120).to_i
      atime = (ENV['atime'] ||  30).to_i
      Find.find(RAILS_ROOT + "/tmp/sessions/") do |path|
        if FileTest.directory?(path)
          if File.basename(path)[0] == ?.
            Find.prune
          else
            next
          end
        else
          File.delete(path) if File.ctime(path) < ctime.minutes.ago or File.atime(path) < atime.minutes.ago
        end
      end
    end
  end
end

It can be run with 2 optional parameters: “atime”, which defines the time in minutes that will be compared against the last access time of a session file and “ctime” which defines the time in minutes that will be compared against the creation time of a session file. The default values are: ctime = 120 (minutes) and atime = 20 (miuntes) which means that the session files not accessed in the last 20 minutes and created earlier than 2 hours ago will be removed when the script runs.

You can run it like this (I’m overriding default time parameters in the example):

rake tmp:sessions:clear_expired atime=15 ctime=60

Of course you’ll set up a cron to run the script periodiacally and clear expired sessions for you, but please note that the actuall maximum session lifetime will be atime + the time between 2 script runs.

Custom Configuration Info in Rails

2007-07-25T00:00:00+04:00

I think most applications deal with some kind of configuration parameters like admin emails, directory paths or whatever. Sometimes having a bunch of constants in environment.rb is fine, but when you have several developers working on a project and each of them may have their own values and can add new parameters you need a clean solution to handle that.

The common practice is to have an “example” config file under version control (like database.example.yml in mephisto) which is used by all developers to create their local files with custom values. That works OK until someone adds a new parameter to the example file and some careless developer (me) doesn’t notice it in the svn logs, forgets to update his local file and gets a broken application. So I thought that I need a file under version control with default values which is actually used by the application and an ability to have another file with local values that will override the default.

I’ve googled for a ready-made solution and found this one which I liked, but as I’ve just said I also wanted to override the default settings in a local file and also wanted yml file to be parsed with ERB so that I could use Ruby in it (for example if I needed to use RAILS_ROOT to define some path). And so I’ve ended up with my first rails plugin :)

The plugin allows you to have a config.yml file with a “common” section that contains all configuration parameters with their default values and a section for each Rails environment (like development, test, production or your custom one) where you can override the values from the common section. Just put this file under version control, update it with new parameters and all developers will have it with the next update. If someone needs his own specific values, he can simply create a config.local.yml file and override any value there, again having a “common” section and a section for each environment. Nothing is mandatory (files, sections) – you just have what you really need.

An example of a config file:

common:
  admin_email: admin@domain.com
  xml_rpc_url: http://domain.com:8000/
  media_path: <%= RAILS_ROOT %>/tmp/media

development:
  xml_rpc_url: http://localhost:8000/

test:
  xml_rpc_url: http://localhost:8008/

Then, in the application you can use the config parameters like this:

Conf.xml_rpc_url

So it means that you’ve got a Conf object which holds all the configuration parameters defined. It doesn’t allow to change the values in the application code, BTW (so that a typo in a if statement won’t cause weird errors :)).

You can give it a try if you like:

script/plugin install git://github.com/eugenebolshakov/app_config.git

Comments and suggestions are welcome of course ;)

Update: I’ve renamed the configuration variable from Config to Conf.