Sinatra¶ ↑
Atenção: Este documento é apenas uma tradução da versão em inglês e pode estar desatualizado.*
Alguns dos trechos de código a seguir utilizam caracteres UTF-8. Então,
caso esteja utilizando uma versão de ruby inferior à 2.0.0
,
adicione o encoding no início de seus arquivos:
# encoding: utf-8
Sinatra é uma DSL para criar aplicações web em Ruby com o mínimo de esforço e rapidez:
# minha_app.rb require 'sinatra' get '/' do 'Olá Mundo!' end
Instale a gem:
gem install sinatra
Em seguida execute:
ruby minha_app.rb
Acesse em: localhost:4567
Códigos alterados só terão efeito após você reiniciar o servidor. Por favor, reinicie o servidor após qualquer mudança ou use sinatra/reloader.
É recomendado também executar gem install thin
. Caso esta gem
esteja disponível, o Sinatra irá utilizá-la.
Conteúdo¶ ↑
Sinatra Conteúdo Rotas Condições Valores Retornados Validadores de rota personalizados Arquivos estáticos Views / Templates Literal Templates Linguagens de template disponíveis Haml Templates Erb Templates Builder Templates Nokogiri Templates Sass Templates SCSS Templates Less Templates Liquid Templates Markdown Templates Textile Templates RDoc Templates AsciiDoc Templates Radius Templates Markaby Templates RABL Templates Slim Templates Creole Templates MediaWiki Templates CoffeeScript Templates Stylus Templates Yajl Templates WLang Templates Acessando Variáveis nos Templates Templates com yield e layouts aninhados Templates Inline Templates Nomeados Associando extensões de arquivos Adicionando seu Próprio Engine de Template Customizando lógica para encontrar templates Filtros Helpers Utilizando Sessões Segurança Secreta da Sessão Configuração da Sessão Escolhande Seu Próprio Middleware de Sessão Halting Passing Desencadeando Outra Rota Definindo Corpo, Código de Status e Cabeçalhos Transmitindo Respostas Usando Logs Tipos Mime Gerando URLS Redirecionamento do Navegador Controle de Cache Enviando Arquivos Acessando o Objeto de Requisição Anexos Trabalhando com Data e Hora Procurando Arquivos de Modelo Configuração Configurando proteção a ataques Configurações Disponíveis Ambientes Tratamento de Erros Não Encontrado Erro Rack Middleware Testando Sinatra::Base - Middleware, Bibliotecas e Aplicações Modulares Modular vs. Estilo Clássico Servindo uma Aplicação Modular Usando uma Aplicação de Estilo Clássico com um config.ru Quando usar um config.ru? Usando Sinatra como Middleware Criação de Aplicações Dinâmicas Escopos e Ligação Escopo de Aplicação/Classe Escopo de Instância/Requisição Escopo de Delegação Linha de comando Multi-threading Requerimentos A última versão Com Bundler Versionando Mais
Rotas¶ ↑
No Sinatra, uma rota é um método HTTP emparelhado com um padrão de URL. Cada rota possui um bloco de execução:
get '/' do .. mostrando alguma coisa .. end post '/' do .. criando alguma coisa .. end put '/' do .. atualizando alguma coisa .. end patch '/' do .. modificando alguma coisa .. end delete '/' do .. removendo alguma coisa .. end options '/' do .. estabelecendo alguma coisa .. end link '/' do .. associando alguma coisa .. end unlink '/' do .. separando alguma coisa .. end
As rotas são interpretadas na ordem em que são definidas. A primeira rota encontrada responde a requisição.
Rotas com barras à direita são diferentes das que não contém as barras:
get '/foo' do # Não é o mesmo que "GET /foo/" end
Padrões de rota podem conter parâmetros nomeados, acessíveis por meio do
hash params
:
get '/ola/:nome' do # corresponde a "GET /ola/foo" e "GET /ola/bar" # params['nome'] é 'foo' ou 'bar' "Olá #{params['nome']}!" end
Você também pode acessar parâmetros nomeados por meio dos parâmetros de um bloco:
get '/ola/:nome' do |n| # corresponde a "GET /ola/foo" e "GET /ola/bar" # params['nome'] é 'foo' ou 'bar' # n guarda o valor de params['nome'] "Olá #{n}!" end
Padrões de rota também podem conter parâmetros splat (curinga), acessível
por meio do array params['splat']
:
get '/diga /para ' do # corresponde a /diga/ola/para/mundo params['splat'] # => ["ola", "mundo"] end get '/download/*.*' do # corresponde a /download/caminho/do/arquivo.xml params['splat'] # => ["caminho/do/arquivo", "xml"] end
Ou com parâmetros de um bloco:
get '/download/*.*' do |caminho, ext| [caminho, ext] # => ["caminho/do/arquivo", "xml"] end
Rotas podem casar com expressões regulares:
get /\/ola\/([\w]+)/ do "Olá, #{params['captures'].first}!" end
Ou com parâmetros de um bloco:
get %r{/ola/([\w]+)} do |c| # corresponde a "GET /meta/ola/mundo", "GET /ola/mundo/1234" etc. "Olá, #{c}!" end
Padrões de rota podem contar com parâmetros opcionais:
get '/posts/:formato?' do # corresponde a "GET /posts/" e qualquer extensão "GET /posts/json", "GET /posts/xml", etc. end
Rotas também podem utilizar query strings:
get '/posts' do # corresponde a "GET /posts?titulo=foo&autor=bar" titulo = params['titulo'] autor = params['autor'] # utiliza as variaveis titulo e autor; a query é opicional para a rota /posts end
A propósito, a menos que você desative a proteção contra ataques (veja abaixo), o caminho solicitado pode ser alterado antes de concluir a comparação com as suas rotas.
Você pode customizar as opções usadas do Mustermann para uma
rota passando :mustermann_opts
num hash:
get '\A/posts\z', :musterman_opts => { :type => regexp, :check_anchors => false } do # corresponde a /posts exatamente, com ancoragem explícita "Se você combinar um padrão ancorado bata palmas!" end
Parece com uma condição mas não é! Essas opções
serão misturadas no hash global :mustermann_opts
descrito abaixo
Condições¶ ↑
Rotas podem incluir uma variedade de condições, tal como o user
agent
:
get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do "Você está usando o Songbird versão #{params['agent'][0]}" end get '/foo' do # Correspondente a navegadores que não sejam Songbird end
Outras condições disponíveis são host_name
e
provides
:
get '/', :host_name => /^admin\./ do "Área administrativa. Acesso negado!" end get '/', :provides => 'html' do haml :index end get '/', :provides => ['rss', 'atom', 'xml'] do builder :feed end
provides
procura o cabeçalho Accept das requisições
Você pode facilmente definir suas próprias condições:
set(:probabilidade) { |valor| condition { rand <= valor } } get '/ganha_um_carro', :probabilidade => 0.1 do "Você ganhou!" end get '/ganha_um_carro' do "Sinto muito, você perdeu." end
Use splat, para uma condição que leva vários valores:
set(:auth) do |*roles| # <- observe o splat aqui condition do unless logged_in? && roles.any? {|role| current_user.in_role? role } redirect "/login/", 303 end end end get "/minha/conta/", :auth => [:usuario, :administrador] do "Detalhes da sua conta" end get "/apenas/administrador/", :auth => :administrador do "Apenas administradores são permitidos aqui!" end
Retorno de valores¶ ↑
O valor de retorno do bloco de uma rota determina pelo menos o corpo da
resposta passado para o cliente HTTP, ou pelo menos o próximo middleware na
pilha Rack. Frequentemente, isto é uma
string
, tal como nos exemplos acima. Entretanto, outros
valores também são aceitos.
Você pode retornar uma resposta válida ou um objeto para o Rack, sendo eles de qualquer tipo de objeto que queira. Além disso, é possível retornar um código de status HTTP.
Um array com três elementros: [status (Integer), cabecalho (Hash),
corpo da resposta (responde à #each)]
Um array com dois elementros: [status (Integer), corpo da resposta
(responde à #each)]
Um objeto que responda à #each
sem passar nada, mas, sim,
strings
para um dado bloco
Um objeto Integer
representando o código de status
Dessa forma, podemos implementar facilmente um exemplo de streaming:
class Stream def each 100.times { |i| yield "#{i}\n" } end end get('/') { Stream.new }
Você também pode usar o método auxiliar stream
(descrito abaixo) para reduzir códigos
boilerplate e para incorporar a lógica de streaming (transmissão) na rota.
Validadores de Rota Personalizados¶ ↑
Como apresentado acima, a estrutura do Sinatra conta com suporte embutido para uso de padrões de String e expressões regulares como validadores de rota. No entanto, ele não pára por aí. Você pode facilmente definir os seus próprios validadores:
class AllButPattern Match = Struct.new(:captures) def initialize(except) @except = except @captures = Match.new([]) end def match(str) @captures unless @except === str end end def all_but(pattern) AllButPattern.new(pattern) end get all_but("/index") do # ... end
Note que o exemplo acima pode ser robusto e complicado em excesso. Pode também ser implementado como:
get // do pass if request.path_info == "/index" # ... end
Ou, usando algo mais denso à frente:
get %r{(?!/index)} do # ... end
Arquivos estáticos¶ ↑
Arquivos estáticos são disponibilizados a partir do diretório
./public
. Você pode especificar um local diferente pela opção
:public_folder
set :public_folder, __dir__ + '/estatico'
Note que o nome do diretório público não é incluido na URL. Um arquivo
./public/css/style.css
é disponibilizado como
http://exemplo.com/css/style.css
.
Use a configuração :static_cache_control
(veja abaixo) para adicionar a informação
Cache-Control
no cabeçalho.
Views / Templates¶ ↑
Cada linguagem de template é exposta através de seu próprio método de renderização. Estes métodos simplesmente retornam uma string:
get '/' do erb :index end
Isto renderiza views/index.rb
Ao invés do nome do template, você também pode passar direto o conteúdo do template:
get '/' do code = "<%= Time.now %>" erb code end
Templates também aceitam como um segundo argumento, um hash de opções:
get '/' do erb :index, :layout => :post end
Isto irá renderizar a views/index.erb
inclusa dentro da
views/post.erb
(o padrão é a views/layout.erb
, se
existir).
Qualquer opção não reconhecida pelo Sinatra será passada adiante para o engine de template:
get '/' do haml :index, :format => :html5 end
Você também pode definir opções padrões para um tipo de template:
set :haml, :format => :html5 get '/' do haml :index end
Opções passadas para o método de renderização sobrescreve as opções
definitas através do método set
.
Opções disponíveis:
- locals
- Lista de locais passado para o documento. Conveniente para *partials* Exemplo: erb "<%= foo %>", :locals => {:foo => "bar"}
- default_encoding
- String encoding para ser utilizada em caso de incerteza. o padrão é settings.default_encoding.
- views
- Diretório de onde os templates são carregados. O padrão é settings.views.
- layout
- Para definir quando utilizar ou não um layout (true ou false). E se for um Symbol, especifica qual template usar. Exemplo: erb :index, :layout => !request.xhr?
- content_type
- O *Content-Type* que o template produz. O padrão depente da linguagem de template utilizada.
- scope
- Escopo em que o template será renderizado. Padrão é a instância da aplicação. Se você mudar isto as variáveis de instância métodos auxiliares não serão disponibilizados.
- layout_engine
- A engine de template utilizada para renderizar seu layout. Útil para linguagens que não suportam templates de outra forma. O padrão é a engine do template utilizado. Exemplo: set :rdoc, :layout_engine => :erb
- layout_options
- Opções especiais utilizadas apenas para renderizar o layout. Exemplo: set :rdoc, :layout_options => { :views => 'views/layouts' }
É pressuposto que os templates estarão localizados diretamente sob o
diretório ./views
. Para usar um diretório diferente:
set :views, settings.root + '/templates'
Uma coisa importante para se lembrar é que você sempre deve referenciar os
templates utilizando symbols, mesmo que eles estejam em um
subdiretório (neste caso use: :'subdir/template'
or
'subdir/template'.to_sym
). Você deve utilizar um
symbol porque senão o método de renderização irá renderizar
qualquer outra string que você passe diretamente para ele
Literal Templates¶ ↑
get '/' do haml '%div.title Olá Mundo' end
Renderiza um template string. Você pode opcionalmente especificar
path
e :line
para um backtrace mais claro se
existir um caminho do sistema de arquivos ou linha associada com aquela
string.
get '/' do haml '%div.title Olá Mundo', :path => 'exemplos/arquivo.haml', :line => 3 end
Linguagens de template disponíveis¶ ↑
Algumas linguagens possuem multiplas implementações. Para especificar qual implementação deverá ser utilizada (e para ser thread-safe), você deve requere-la primeiro:
require 'rdiscount' # ou require 'bluecloth' get('/') { markdown :index }
Haml Templates¶ ↑
Dependência | haml |
Extensão do Arquivo | .haml |
Exemplo | haml :index, :format => :html5 |
Erb Templates¶ ↑
Dependência | erubis or erb (included in Ruby) |
Extensão dos Arquivos | .erb, .rhtml or .erubis (Erubis only) |
Exemplo | erb :index |
Builder Templates¶ ↑
Dependêcia | builder |
Extensão do Arquivo | .builder |
Exemplo | builder { |xml| xml.em "hi" } |
It also takes a block for inline templates (see exemplo).
Nokogiri Templates¶ ↑
Dependência | nokogiri |
Extensão do Arquivo | .nokogiri |
Exemplo | nokogiri { |xml| xml.em "hi" } |
It also takes a block for inline templates (see exemplo).
Sass Templates¶ ↑
Dependência | sass |
Extensão do Arquivo | .sass |
Exemplo | sass :stylesheet, :style => :expanded |
SCSS Templates¶ ↑
Dependência | sass |
Extensão do Arquivo | .scss |
Exemplo | scss :stylesheet, :style => :expanded |
Less Templates¶ ↑
Dependência | less |
Extensão do Arquivo | .less |
Exemplo | less :stylesheet |
Liquid Templates¶ ↑
Dependência | liquid |
Extensão do Arquivo | .liquid |
Exemplo | liquid :index, :locals => { :key => 'value' } |
Já que você não pode chamar o Ruby (exceto pelo método yield
)
pelo template Liquid, você quase sempre precisará passar o
locals
para ele.
Markdown Templates¶ ↑
Dependência | Anyone of: RDiscount , RedCarpet , BlueCloth , kramdown , maruku |
Extensão do Arquivos | .markdown, .mkd and .md |
Exemplo | markdown :index, :layout_engine => :erb |
Não é possível chamar métodos por este template, nem passar locals para o mesmo. Portanto normalmente é utilizado junto a outra engine de renderização:
erb :overview, :locals => { :text => markdown(:introducao) }
Note que vcoê também pode chamar o método markdown
dentro de
outros templates:
Já que você não pode chamar o Ruby pelo Markdown, você não pode utilizar um
layout escrito em Markdown. Contudo é possível utilizar outra engine de
renderização como template, deve-se passar a :layout_engine
como opção.
Dependência | RedCloth |
Extensão do Arquivo | .textile |
Exemplo | textile :index, :layout_engine => :erb |
Não é possível chamar métodos por este template, nem passar locals para o mesmo. Portanto normalmente é utilizado junto a outra engine de renderização:
erb :overview, :locals => { :text => textile(:introducao) }
Note que vcoê também pode chamar o método textile
dentro de
outros templates:
Já que você não pode chamar o Ruby pelo Textile, você não pode utilizar um
layout escrito em Textile. Contudo é possível utilizar outra engine de
renderização como template, deve-se passar a :layout_engine
como opção.
RDoc Templates¶ ↑
Dependência | RDoc |
Extensão do Arquivo | .rdoc |
Exemplo | rdoc :README, :layout_engine => :erb |
Não é possível chamar métodos por este template, nem passar locals para o mesmo. Portanto normalmente é utilizado junto a outra engine de renderização:
erb :overview, :locals => { :text => rdoc(:introducao) }
Note que vcoê também pode chamar o método rdoc
dentro de
outros templates:
Já que você não pode chamar o Ruby pelo RDoc, você não pode utilizar um
layout escrito em RDoc. Contudo é possível utilizar outra engine de
renderização como template, deve-se passar a :layout_engine
como opção.
AsciiDoc Templates¶ ↑
Dependência | Asciidoctor |
Extensão do Arquivo | .asciidoc, .adoc and .ad |
Exemplo | asciidoc :README, :layout_engine => :erb |
Já que você não pode chamar o Ruby pelo template AsciiDoc, você quase
sempre precisará passar o locals
para ele.
Radius Templates¶ ↑
Dependência | Radius |
Extensão do Arquivo | .radius |
Exemplo | radius :index, :locals => { :key => 'value' } |
Já que você não pode chamar o Ruby pelo template Radius, você quase sempre
precisará passar o locals
para ele.
Markaby Templates¶ ↑
Dependência | Markaby |
Extensão do Arquivo | .mab |
Exemplo | markaby { h1 "Welcome!" } |
Este também recebe um bloco para templates (veja o exemplo).
RABL Templates¶ ↑
Dependência | Rabl |
Extensão do Arquivo | .rabl |
Exemplo | rabl :index |
Slim Templates¶ ↑
Dependência | Slim Lang |
Extensão do Arquivo | .slim |
Exemplo | slim :index |
Creole Templates¶ ↑
Dependência | Creole |
Extensão do Arquivo | .creole |
Exemplo | creole :wiki, :layout_engine => :erb |
Não é possível chamar métodos por este template, nem passar locals para o mesmo. Portanto normalmente é utilizado junto a outra engine de renderização:
erb :overview, :locals => { :text => creole(:introduction) }
Note que você também pode chamar o método creole
dentro de
outros templates:
Já que você não pode chamar o Ruby pelo Creole, você não pode utilizar um
layout escrito em Creole. Contudo é possível utilizar outra engine de
renderização como template, deve-se passar a :layout_engine
como opção.
MediaWiki Templates¶ ↑
Dependência | WikiCloth |
Extensão do Arquivo | .mediawiki and .mw |
Exemplo | mediawiki :wiki, :layout_engine => :erb |
It is not possible to call methods from MediaWiki markup, nor to pass locals to it. You therefore will usually use it in combination with another rendering engine:
erb :overview, :locals => { :text => mediawiki(:introduction) }
Note that you may also call the mediawiki
method from within
other templates:
Já que você não pode chamar o Ruby pelo MediaWiki, você não pode utilizar
um layout escrito em MediaWiki. Contudo é possível utilizar outra engine de
renderização como template, deve-se passar a :layout_engine
como opção.
CoffeeScript Templates¶ ↑
Dependência | CoffeeScript and a way to execute javascript |
Extensão do Arquivo | .coffee |
Exemplo | coffee :index |
Stylus Templates¶ ↑
Dependência | Stylus and a way to execute javascript |
Extensão do Arquivo | .styl |
Exemplo | stylus :index |
Antes que vcoê possa utilizar o template Stylus primeiro você deve carregar
stylus
e stylus/tilt
:
require 'sinatra' require 'stylus' require 'stylus/tilt' get '/' do stylus :exemplo end
Yajl Templates¶ ↑
Dependência | yajl-ruby |
Extensão do Arquivo | .yajl |
Exemplo | yajl :index, :locals => { :key => 'qux' }, :callback => 'present', :variable => 'resource' |
O código-fonte do template é executado como uma string Ruby e a variável
resultante em json é convertida utilizando #to_json
:
json = { :foo => 'bar' } json[:baz] = key
O :callback
e :variable
são opções que podem ser
utilizadas para o objeto de renderização:
var resource = {"foo":"bar","baz":"qux"}; present(resource);
WLang Templates¶ ↑
Dependência | WLang |
Extensão do Arquivo | .wlang |
Exemplo | wlang :index, :locals => { :key => 'value' } |
Já que você não pode chamar o Ruby (exceto pelo método yield
)
pelo template WLang, você quase sempre precisará passar o
locals
para ele.
Acessando Variáveis nos Templates¶ ↑
Templates são avaliados dentro do mesmo contexto como manipuladores de rota. Variáveis de instância definidas em manipuladores de rota são diretamente acessadas por templates:
get '/:id' do @foo = Foo.find(params['id']) haml '%h1= @foo.nome' end
Ou, especifique um hash explícito de variáveis locais:
get '/:id' do foo = Foo.find(params['id']) haml '%h1= foo.nome', :locals => { :foo => foo } end
Isso é tipicamente utilizando quando renderizamos templates como partials dentro de outros templates.
Templates com yield
e layouts aninhados¶ ↑
Um layout geralmente é apenas um template que executa yield
.
Tal template pode ser utilizado pela opção :template
descrita
acima ou pode ser renderizado através de um bloco, como a seguir:
erb :post, :layout => false do erb :index end
Este código é quase equivalente a erb :index, :layout =>
:post
Passando blocos para os métodos de renderização é útil para criar layouts aninhados:
erb :main_layout, :layout => false do erb :admin_layout do erb :user end end
Também pode ser feito com menos linhas de código:
erb :admin_layout, :layout => :main_layout do erb :user end
Atualmente os métodos listados aceitam blocos: erb
,
haml
, liquid
, slim
,
wlang
. E o método geral render
também aceita
blocos.
Templates Inline¶ ↑
Templates podem ser definidos no final do arquivo fonte:
require 'sinatra' get '/' do haml :index end __END__
NOTA: Templates inline definidos no arquivo fonte são automaticamente
carregados pelo Sinatra. Digite enable
:inline_templates
explicitamente se você tem templates inline em
outros arquivos fonte.
Templates Nomeados¶ ↑
Templates também podem ser definidos utilizando o método top-level
template
:
template :layout do "%html\n =yield\n" end template :index do '%div.title Olá Mundo!' end get '/' do haml :index end
Se existir um template com nome “layout”, ele será utilizado toda vez que
um template for renderizado. Você pode desabilitar layouts passando
:layout => false
ou desabilita-los por padrão via set
:haml, :layout => false
get '/' do haml :index, :layout => !request.xhr? end
Associando Extensões de Arquivos¶ ↑
Para associar uma extensão de arquivo com um engine de template use o
método Tilt.register
. Por exemplo, se você quiser usar a
extensão tt
para os templates Textile você pode fazer o
seguinte:
Tilt.register :tt, Tilt[:textile]
Adicionando seu Próprio Engine de Template¶ ↑
Primeiro registre seu engine utilizando o Tilt, e então crie um método de renderização:
Tilt.register :myat, MyAwesomeTemplateEngine helpers do def myat(*args) render(:myat, *args) end end get '/' do myat :index end
Renderize ./views/index.myat
. Aprenda mais sobre o Tilt aqui.
Customizando Lógica para Encontrar Templates¶ ↑
Para implementar sua própria lógica para busca de templates você pode
escrever seu próprio método #find_template
configure do set :views [ './views/a', './views/b' ] end def find_template(views, name, engine, &block) Array(views).each do |v| super(v, name, engine, &block) end end
Filtros¶ ↑
Filtros Before são avaliados antes de cada requisição dentro do contexto da requisição e podem modificar a requisição e a reposta. Variáveis de instância definidas nos filtros são acessadas através de rotas e templates:
before do @nota = 'Oi!' request.path_info = '/foo/bar/baz' end get '/foo/*' do @nota #=> 'Oi!' params['splat'] #=> 'bar/baz' end
Filtros After são avaliados após cada requisição dentro do mesmo contexto da requisição e também podem modificar a requisição e a resposta. Variáveis de instância definidas nos filtros before e rotas são acessadas através dos filtros after:
after do puts response.status end
Nota: A não ser que você use o metódo body
ao invés de apenas
retornar uma String das rotas, o corpo ainda não estará disponível no
filtro after, uma vez que é gerado depois.
Filtros opcionalmente têm um padrão, fazendo com que sejam avaliados somente se o caminho do pedido coincidir com esse padrão:
before '/protected/*' do authenticate! end after '/create/:slug' do |slug| session[:last_slug] = slug end
Como rotas, filtros também aceitam condições:
before :agent => /Songbird/ do #... end after '/blog/*', :host_name => 'exemplo.com' do #... end
Helpers¶ ↑
Use o método de alto nível helpers
para definir métodos
auxiliares para utilizar em manipuladores de rotas e modelos:
helpers do def bar(nome) "#{nome}bar" end end get '/:nome' do bar(params['nome']) end
Alternativamente, métodos auxiliares podem ser definidos separadamente em módulos:
module FooUtils def foo(nome) "#{nome}foo" end end module BarUtils def bar(nome) "#{nome}bar" end end helpers FooUtils, BarUtils
O efeito é o mesmo que incluir os módulos na classe da aplicação.
Utilizando Sessões¶ ↑
Uma sessão é usada para manter o estado durante requisições. Se ativada, você terá disponível um hash de sessão para cada sessão de usuário:
enable :sessions get '/' do "value = " << session[:value].inspect end get '/:value' do session['value'] = params['value'] end
Segredo Seguro da Sessão¶ ↑
Para melhorar a segurança, os dados da sessão no cookie são assinado com
uma segredo de sessão usando HMAC-SHA1
. Esse segredo de sessão
deve ser, de preferência, um valor criptograficamente randômico, seguro, de
um comprimento apropriado no qual HMAC-SHA1
é maior ou igual a
64 bytes (512 bits, 128 carecteres hexadecimais). Você será avisado para
não usar uma chave secreta menor que 32 bytes de randomicidade (256 bits,
64 caracteres hexadecimais). Portanto, é muito importante
que você não invente o segredo, mas use um gerador de números aleatórios
seguro para cria-lo. Humanos são extremamente ruins em gerar números
aleatórios.
Por padrão, um segredo de sessão aleatório seguro de 32 bytes é gerada para você pelo Sinatra, mas ele mudará toda vez que você reiniciar sua aplicação. Se você tiver múltiplas instâncias da sua aplicação e você deixar que o Sinatra gere a chave, cada instância teria uma chave de sessão diferente, o que certamente não é o que você quer.
Para melhor segurança e usabilidade é recomendado que você gere um segredo randômico secreto e salve-o em uma variável de ambiente em cada host rodando sua aplicação, assim todas as instâncias da sua aplicação irão compartilhar o mesmo segredo. Você deve, periodicamente, mudar esse segredo de sessão para um novo valor. Abaixo, são mostrados alguns exemplos de como você pode criar um segredo de 64 bytes e usa-lo:
Gerando Segredo de Sessão**
$ ruby -e "require 'securerandom'; puts SecureRandom.hex(64)" 99ae8af...snip...ec0f262ac
Gerando Segredo de Sessão (Pontos adicionais)**
Use preferencialmente a gem sysrandom
para utilizar as facilidades do sistema RNG para gerar valores aleatórios
ao invés do OpenSSL
no qual o MRI Ruby padroniza para:
$ gem install sysrandom Building native extensions. This could take a while... Sucessfully installed sysrandom-1.x 1 gem installed $ ruby -e "require 'sysrandom/securerandom'; puts SecureRandom.hex(64)" 99ae8af...snip...ec0f262ac
Segredo de Sessão numa Variável de Ambiente**
Defina uma variável de ambiente SESSION_SECRET
para o Sinatra com o valor que você gerou. Salve esse
valor entre as reinicializações do seu host. Já que a forma de fazer isso
irá variar entre os sistemas operacionais, o exemplo abaixo serve apenas
para fins ilustrativos:
# echo "export SESSION_SECRET = 99ae8af...snip...ec0f262ac" >> ~/.bashrc
Configurando o Segredo de Sessão na Aplicação**
Configure sua aplicação para uma falha de segredo seguro aleatório se a
variável de ambiente SESSION_SECRET
não estiver disponível.
Como ponto adicional use a gem sysrandom da seguinte forma:
require 'securerandom' # -or- require 'sysrandom/securearandom' set :session_secret, ENV.fecth(`SESSION_SECRET`) { SecureRandom.hex(64) }
Configuração de Sessão¶ ↑
Se você deseja configurar isso adicionalmente, você pode salvar um hash com
opções na definição de sessions
:
set :sessions, :domain => 'foo.com'
Para compartilhar sua sessão com outras aplicações no subdomínio de foo.com, adicione um . antes do domínio como no exemplo abaixo:
set :sessions, :domain => '.foo.com'
Escolhendo Seu Próprio Middleware de Sessão¶ ↑
Perceba que enable :sessions
na verdade guarda todos seus
dados num cookie. Isto pode não ser o que você deseja sempre (armazenar
muitos dados irá aumentar seu tráfego, por exemplo). Você pode usar
qualquer middleware de sessão Rack para fazer isso,
um dos seguintes métodos pode ser usado:
enable :sessions set :session_store, Rack::Session::Pool
Ou definir as sessões com um hash de opções:
set :sessions, :expire_after => 2592000 set :session_store, Rack::Session::Pool
Outra opção é não usar enable :sessions
, mas
ao invés disso trazer seu middleware escolhido como você faria com qualquer
outro middleware.
É importante lembrar que usando esse método, a proteção baseada na sessão não estará habilitada por padrão**.
Para o middleware Rack fazer isso, será preciso que isso também seja adicionado:
use Rack::Session::Pool, :expire_after => 2592000 use Rack::Protection::RemoteToken use Rack::Protection::SessionHijacking
Veja 'Configurando proteção a ataques' para mais informações.
Parando¶ ↑
Para parar imediatamente uma requisição com um filtro ou rota utilize:
halt
Você também pode especificar o status quando parar:
halt 410
Ou o corpo:
halt 'isso será o corpo'
Ou ambos:
halt 401, 'vá embora!'
Com cabeçalhos:
halt 402, {'Content-Type' => 'text/plain'}, 'revanche'
Também é obviamente possível combinar um template com o halt
:
halt erb(:error)
Passing¶ ↑
Uma rota pode processar aposta para a próxima rota correspondente usando
pass
:
get '/adivinhar/:quem' do pass unless params['quem'] == 'Frank' 'Você me pegou!' end get '/adivinhar/*' do 'Você falhou!' end
O bloqueio da rota é imediatamente encerrado e o controle continua com a próxima rota compatível. Se nenhuma rota compatível for encontrada, um 404 é retornado.
Desencadeando Outra Rota¶ ↑
As vezes o pass
não é o que você quer, ao invés dele talvez
você queira obter o resultado chamando outra rota. Simplesmente utilize o
método call
neste caso:
get '/foo' do status, headers, body = call env.merge("PATH_INFO" => '/bar') [status, headers, body.map(&:upcase)] end get '/bar' do "bar" end
Note que no exemplo acima você ganharia performance e facilitaria os testes
ao simplesmente mover "bar"
para um método auxiliar
usado por ambos /foo
e /bar
.
Se você quer que a requisição seja enviada para a mesma instância da
aplicação no lugar de uma duplicada, use call!
no lugar de
call
.
Veja a especificação do Rack se você quer aprender
mais sobre o call
.
Definindo Corpo, Código de Status e Cabeçalhos¶ ↑
É possível e recomendado definir o código de status e o corpo da resposta
com o valor retornado do bloco da rota. Entretanto, em alguns cenários você
pode querer definir o corpo em um ponto arbitrário do fluxo de execução.
Você pode fazer isso com o metódo auxiliar body
. Se você fizer
isso, poderá usar esse metódo de agora em diante para acessar o body:
get '/foo' do body "bar" end after do puts body end
Também é possivel passar um bloco para body
, que será
executado pelo manipulador Rack (isso pode ser
usado para implementar transmissão, veja
“Retorno de Valores”).
Similar ao corpo, você pode também definir o código de status e cabeçalhos:
get '/foo' do status 418 headers \ "Allow" => "BREW, POST, GET, PROPFIND, WHEN" "Refresh" => "Refresh: 20; https://ietf.org/rfc/rfc2324.txt" body "Eu sou um bule de chá!" end
Assim como body
, headers
e status
sem argumentos podem ser usados para acessar seus valores atuais.
Transmitindo Respostas¶ ↑
As vezes você quer começar a mandar dados enquanto está gerando partes do
corpo da resposta. Em exemplos extremos, você quer continuar enviando dados
até o cliente encerrar a conexão. Você pode usar o método auxiliar
stream
para evitar criar seu próprio empacotador:
get '/' do stream do |out| out << "Isso será len -\n" sleep 0.5 out << " Aguarde \n" sleep 1 out << " dário!\n" end end
Isso permite você implementar APIs de Transmissão, Eventos Enviados pelo Servidor, e pode ser usado como a base para WebSockets. Pode ser usado também para aumentar a taxa de transferência se algum, mas não todo, conteúdo depender de um recurso lento.
Perceba que o comportamento da transmissão, especialmente o número de
requisições concorrentes, depende altamente do servidor web usado para
servir a aplicação. Alguns servidores podem até mesmo não suportar
transmissão de maneira alguma. Se o servidor não suportar transmissão, o
corpo será enviado completamente após que o bloco passado para
stream
terminar de executar. Transmissão não funciona de
nenhuma maneira com Shotun.
Se o parâmetro opcional é definido como keep_open
, ele não
chamará close
no objeto transmitido, permitindo você a
fecha-lo em algum outro ponto futuro no fluxo de execução. Isso funciona
apenas em servidores orientados a eventos, como Thin e Rainbows. Outros
servidores irão continuar fechando a transmissão:
# long polling set :server, :thin conexoes = [] get '/assinar' do # registra o interesse de um cliente em servidores de eventos stream(:keep_open) do |saida| conexoes << saida # retire conexões mortas conexoes.reject!(&:closed?) end end post '/:messagem' do conexoes.each do |saida| # notifica o cliente que uma nova mensagem chegou saida << params['messagem'] << "\n" # indica ao cliente para se conectar novamente saida.close end # confirma "messagem recebida" end
Também é possivel para o cliente fechar a conexão quando está tentando
escrever para o socket. Devido a isso, é recomendado checar
out.closed?
antes de tentar escrever.
Usando Logs¶ ↑
No escopo da requisição, o método auxiliar logger
expõe uma
instância Logger
:
get '/' do logger.info "loading data" # ... end
Esse logger irá automaticamente botar as configurações de log do manipulador Rack na sua conta. Se a produção de logs estiver desabilitads, esse método retornará um objeto dummy, então você não terá que se preocupar com suas rotas e filtros.
Perceba que a produção de logs está habilitada apenas para
Sinatra::Application
por padrão, então se você herdar de
Sinatra::Base
, você provavelmente irá querer habilitar:
class MyApp < Sinatra::Base configure :production, :development do enable :logging end end
Para evitar que qualquer middleware de logs seja configurado, defina a
configuração logging
como nil
. Entretanto, tenha
em mente que logger
retornará, nesse caso, nil
.
Um caso de uso comum é quando você quer definir seu próprio logger. Sinatra irá usar qualquer um que ele achar em
env['rack.logger']
Tipos Mime¶ ↑
Quando se está usando send_file
ou arquivos estáticos, você
pode ter tipos mime que o Sinatra não entende.
Use mime_type
para registrá-los pela extensão do arquivo:
configure do mime_type :foo, 'text/foo' end
Você pode utilizar também com o método auxiliar content_type
:
get '/' do content-type :foo "foo foo foo" end
Gerando URLs¶ ↑
Para gerar URLs você deve usar o metódo auxiliar url
no Haml:
Isso inclui proxies reversos e rotas Rack, se presentes.
Esse método é também apelidado para to
(veja abaixo para um exemplo).
Redirecionamento do Browser¶ ↑
Você pode lançar um redirecionamento no browser com o metódo auxiliar
redirect
:
get '/foo' do redirect to('/bar') end
Quaisquer paramêtros adicionais são interpretados como argumentos passados
ao halt
:
redirect to('/bar'), 303 redirect 'http://www.google.com/', 'lugar errado, amigo'
Você pode também facilmente redirecionar para a página da qual o usuário
veio com redirect back
:
get '/foo' do "<a href='/bar'>do something</a>" end get '/bar' do do_something redirect back end
Para passar argumentos com um redirecionamento, adicione-os a query:
redirect to('/bar?sum=42')
Ou use uma sessão:
enable :sessions get '/foo' do session[:secret] = 'foo' redirect to('/bar') end get '/bar' do session[:secret] end
Controle de Cache¶ ↑
Definir sues cabeçalhos corretamente é o principal passo para uma correta cache HTTP.
Você pode facilmente definir o cabeçalho de Cache-Control como:
get '/' do cache_control :public "guarde isso!" end
Dica profissional: Configure a cache em um filtro anterior:
before do cache_control :public, :must_revalidate, :max_age => 60 end
Se você está usando o método auxiliar expires
para definir seu
cabeçalho correspondente, Cache-Control
irá ser definida
automaticamente para você:
before do expires 500, :public, :must_revalidate end
Para usar propriciamente caches, você deve considerar usar
etag
ou last_modified
. É recomendado chamar esses
métodos auxiliares antes de fazer qualquer tipo de processamento
pesado, já que eles irão imediatamente retornar uma resposta se o cliente
já possui a versão atual na sua cache:
get "/artigo/:id" do @artigo = Artigo.find params['id'] last_modified @artigo.updated_at etag @artigo.sha1 erb :artigo end
Também é possível usar uma ETag fraca:
etag @article.sha1, :weak
Esses métodos auxiliares não irão fazer nenhum processo de cache para você, mas irão alimentar as informações necessárias para sua cache. Se você está pesquisando por uma solução rápida de fazer cache com proxy-reverso, tente rack-cache:
require "rack/cache" require "sinatra" use Rack::Cache get '/' do cache_control :public, :max_age => 36000 sleep 5 "olá" end
Use a configuração :static_cache_control
(veja
[acima]#(controle-de-cache)) para adicionar o cabeçalho de informação
Cache-Control
para arquivos estáticos.
De acordo com a RFC 2616, sua aplicação deve se comportar diferentemente se
o cabeçalho If-Match ou If-None-Match é definido para *
,
dependendo se o recurso requisitado já existe. Sinatra assume que recursos para requisições
seguras (como get) e idempotentes (como put) já existem, enquanto que para
outros recursos (por exemplo requisições post) são tratados como novos
recursos. Você pode mudar esse comportamento passando em uma opção
:new_resource
:
get '/create' do etag '', :new_resource => true Artigo.create erb :novo_artigo end
Se você quer continuar usando um ETag fraco, passe em uma opção
:kind
:
etag '', :new_resource => true, :kind => :weak
Enviando Arquivos¶ ↑
Para retornar os conteúdos de um arquivo como as resposta, você pode usar o
metódo auxiliar send_file
:
get '/' do send_file 'foo.png' end
Também aceita opções:
send_file 'foo.png', :type => :jpg
As opções são:
- filename
- Nome do arquivo a ser usado na respota, o padrão é o nome do arquivo reak
- last_modified
- Valor do cabeçalho Last-Modified, o padrão corresponde ao mtime do arquivo.
- type
- Valor do cabeçalho Content-Type, extraído da extensão do arquivo se inexistente.
- disposition
- Valor do cabeçalho Content-Disposition, valores possíveis: nil (default), :attachment and :inline
- length
- Valor do cabeçalho Content-Length, o padrão corresponde ao tamanho do arquivo.
- status
- Código de status a ser enviado. Útil quando está se enviando um arquivo estático como uma página de erro. Se suportado pelo handler do Rack, outros meios além de transmissão do processo do Ruby serão usados. So você usar esse metódo auxiliar, o Sinatra irá automaticamente lidar com requisições de alcance.
Acessando o Objeto da Requisção¶ ↑
O objeto vindo da requisição pode ser acessado do nível de requsição
(filtros, rotas, manipuladores de erro) através do método
request
:
# app rodando em http://exemplo.com/exemplo get '/foo' do t = %w[text/css text/html application/javascript] request.accept # ['text/html', ' *'] request.accept? 'text/xml' # true request.preferred_type(t) # 'text/html' request.body # corpo da requisição enviado pelo cliente (veja abaixo) request.scheme # "http" request.script_name # "/exemplo" request.path_info # "/foo" request.port # 80 request.request_method # "GET" request.query_string # "" request.content_length # tamanho do request.body request.media_type # tipo de mídia of request.body request.host # "exemplo.com" request.get? # true (metodo similar para outros tipos de requisição) request.form_data? # false request["algum_ param"] # valor do paramêtro 'algum_param'. [] é um atalho para o hash de parametros request.referrer # a referência do cliente ou '/' request.user_agent # agente de usuário (usado por :agent condition) request.cookies # hash dos cookies do browser request.xhr? # isto é uma requisição ajax? request.url # "http://exemplo.com/exemplo/foo" request.path # "/exemplo/foo" request.ip # endereço de IP do cliente request.secure? # false (seria true se a conexão fosse ssl) request.forwarded? # true (se está rodando por um proxy reverso) request.env # raw env hash handed in by Rack end
Algumas opções, como script_name
ou `path_info, podem ser
escritas como:
before { request.path_info = "/" } get "/" do "todas requisições acabam aqui" end
request.body
é uma ES ou um objeo StringIO:
post "/api" do request.body.rewind # em caso de algo já ter lido data = JSON.parse request.body.read "Oi #{data['nome']}!" end
Anexos¶ ↑
Você pode usar o método auxiliar attachment
para dizer ao
navegador que a reposta deve ser armazenada no disco no lugar de ser
exibida no browser:
get '/' do attachment "info.txt" "salve isso!" end
Trabalhando com Data e Hora¶ ↑
O Sinatra oferece um método auxiliar
time_for
que gera um objeto Time do valor dado. É também
possível converter DateTime
, Date
e classes
similares:
get '/' do pass if Time.now > time_for('Dec 23, 2016') "continua no tempo" end
Esse método é usado internamente por expires
,
last_modified
e akin. Você pode portanto facilmente estender o
comportamento desses métodos sobrescrevendo time_for
na sua
aplicação:
helpers do def time_for(valor) case valor when :ontem then Time.now - 24*60*60 when :amanha then Time.now + 24*60*60 else super end end end get '/' do last_modified :ontem expires :amanha "oi" end
Pesquisando por Arquivos de Template¶ ↑
O método auxiliar find_template
é usado para encontrar
arquivos de template para renderizar:
find_template settings.views, 'foo', Tilt[:haml] do |arquivo| puts "pode ser #{arquivo}" end
Isso não é realmente útil. Mas é útil que você possa na verdade sobrescrever esse método para conectar no seu próprio mecanismo de pesquisa. Por exemplo, se você quer ser capaz de usar mais de um diretório de view:
set :views, ['views', 'templates'] helpers do def find_template(views, name, engine, &block) Array(views).each { |v| super(v, name, engine, &block) } end end
Outro exemplo seria utilizando diretórios diferentes para motores (engines) diferentes:
set :views, :sass => 'views/sass', :haml => 'templates', :default => 'views' helpers do def find_template(views, name, engine, &block) _, folder = views.detect { |k,v| engine == Tilt[k] } folder ||= views[:default] super(folder, name, engine, &block) end end
Você pode facilmente embrulhar isso é uma extensão e compartilhar com outras pessoas!
Perceba que find_template
não verifica se o arquivo realmente
existe. Ao invés disso, ele chama o bloco dado para todos os caminhos
possíveis. Isso não significa um problema de perfomance, já que
render
irá usar break
assim que o arquivo é
encontrado. Além disso, as localizações (e conteúdo) de templates serão
guardados na cache se você não estiver rodando no modo de desenvolvimento.
Você deve se lembrar disso se você escrever um método realmente maluco.
Configuração¶ ↑
É possível e recomendado definir o código de status e o corpo da resposta
com o valor retornado do bloco da rota. Entretanto, em alguns cenários você
pode querer definir o corpo em um ponto arbitrário do fluxo de execução.
Você pode fazer isso com o metódo auxiliar body
. Se você fizer
isso, poderá usar esse metódo de agora em diante para acessar o body:
get '/foo' do body "bar" end after do puts body end
Também é possivel passar um bloco para body
, que será
executado pelo manipulador Rack (isso pode ser
usado para implementar transmissão, veja
“Retorno de Valores”).
Similar ao corpo, você pode também definir o código de status e cabeçalhos:
get '/foo' do status 418 headers \ "Allow" => "BREW, POST, GET, PROPFIND, WHEN" "Refresh" => "Refresh: 20; https://ietf.org/rfc/rfc2324.txt" body "Eu sou um bule de chá!" end
Assim como body
, headers
e status
sem argumentos podem ser usados para acessar seus valores atuais.
Transmitindo Respostas¶ ↑
As vezes você quer começar a mandar dados enquanto está gerando partes do
corpo da resposta. Em exemplos extremos, você quer continuar enviando dados
até o cliente encerrar a conexão. Você pode usar o método auxiliar
stream
para evitar criar seu próprio empacotador:
get '/' do stream do |out| out << "Isso será len -\n" sleep 0.5 out << " Aguarde \n" sleep 1 out << " dário!\n" end end
Isso permite você implementar APIs de Transmissão, Eventos Enviados pelo Servidor, e pode ser usado como a base para WebSockets. Pode ser usado também para aumentar a taxa de transferência se algum, mas não todo, conteúdo depender de um recurso lento.
Perceba que o comportamento da transmissão, especialmente o número de
requisições concorrentes, depende altamente do servidor web usado para
servir a aplicação. Alguns servidores podem até mesmo não suportar
transmissão de maneira alguma. Se o servidor não suportar transmissão, o
corpo será enviado completamente após que o bloco passado para
stream
terminar de executar. Transmissão não funciona de
nenhuma maneira com Shotun.
Se o parâmetro opcional é definido como keep_open
, ele não
chamará close
no objeto transmitido, permitindo você a
fecha-lo em algum outro ponto futuro no fluxo de execução. Isso funciona
apenas em servidores orientados a eventos, como Thin e Rainbows. Outros
servidores irão continuar fechando a transmissão:
# long polling set :server, :thin conexoes = [] get '/assinar' do # registra o interesse de um cliente em servidores de eventos stream(:keep_open) do |saida| conexoes << saida # retire conexões mortas conexoes.reject!(&:closed?) end end post '/:messagem' do conexoes.each do |saida| # notifica o cliente que uma nova mensagem chegou saida << params['messagem'] << "\n" # indica ao cliente para se conectar novamente saida.close end # confirma "messagem recebida" end
Também é possivel para o cliente fechar a conexão quando está tentando
escrever para o socket. Devido a isso, é recomendado checar
out.closed?
antes de tentar escrever.
Usando Logs¶ ↑
No escopo da requisição, o método auxiliar logger
expõe uma
instância Logger
:
get '/' do logger.info "loading data" # ... end
Esse logger irá automaticamente botar as configurações de log do manipulador Rack na sua conta. Se a produção de logs estiver desabilitads, esse método retornará um objeto dummy, então você não terá que se preocupar com suas rotas e filtros.
Perceba que a produção de logs está habilitada apenas para
Sinatra::Application
por padrão, então se você herdar de
Sinatra::Base
, você provavelmente irá querer habilitar:
class MyApp < Sinatra::Base configure :production, :development do enable :logging end end
Para evitar que qualquer middleware de logs seja configurado, defina a
configuração logging
como nil
. Entretanto, tenha
em mente que logger
retornará, nesse caso, nil
.
Um caso de uso comum é quando você quer definir seu próprio logger. Sinatra irá usar qualquer um que ele achar em
env['rack.logger']
Tipos Mime¶ ↑
Quando se está usando send_file
ou arquivos estáticos, você
pode ter tipos Mime que o Sinatra não entende.
Use mime_type
para registrá-los pela extensão do arquivo:
configure do mime_type :foo, 'text/foo' end
Você pode utilizar também com o método auxiliar content_type
:
get '/' do content-type :foo "foo foo foo" end
Gerando URLs¶ ↑
Para gerar URLs você deve usar o metódo auxiliar url
no Haml:
Isso inclui proxies reversos e rotas Rack, se presentes.
Esse método é também apelidado para to
(veja abaixo para um exemplo).
Redirecionamento do Browser¶ ↑
Você pode lançar um redirecionamento no browser com o metódo auxiliar
redirect
:
get '/foo' do redirect to('/bar') end
Quaisquer paramêtros adicionais são interpretados como argumentos passados
ao halt
:
redirect to('/bar'), 303 redirect 'http://www.google.com/', 'lugar errado, amigo'
Você pode também facilmente redirecionar para a página da qual o usuário
veio com redirect back
:
get '/foo' do "<a href='/bar'>do something</a>" end get '/bar' do do_something redirect back end
Para passar argumentos com um redirecionamento, adicione-os a query:
redirect to('/bar?sum=42')
Ou use uma sessão:
enable :sessions get '/foo' do session[:secret] = 'foo' redirect to('/bar') end get '/bar' do session[:secret] end
Controle de Cache¶ ↑
Definir sues cabeçalhos corretamente é o principal passo para uma correta cache HTTP.
Você pode facilmente definir o cabeçalho de Cache-Control como:
get '/' do cache_control :public "guarde isso!" end
Dica profissional: Configure a cache em um filtro anterior:
before do cache_control :public, :must_revalidate, :max_age => 60 end
Se você está usando o método auxiliar expires
para definir seu
cabeçalho correspondente, Cache-Control
irá ser definida
automaticamente para você:
before do expires 500, :public, :must_revalidate end
Para usar propriciamente caches, você deve considerar usar
etag
ou last_modified
. É recomendado chamar esses
métodos auxiliares antes de fazer qualquer tipo de processamento
pesado, já que eles irão imediatamente retornar uma resposta se o cliente
já possui a versão atual na sua cache:
get "/artigo/:id" do @artigo = Artigo.find params['id'] last_modified @artigo.updated_at etag @artigo.sha1 erb :artigo end
Também é possível usar uma ETag fraca:
etag @article.sha1, :weak
Esses métodos auxiliares não irão fazer nenhum processo de cache para você, mas irão alimentar as informações necessárias para sua cache. Se você está pesquisando por uma solução rápida de fazer cache com proxy-reverso, tente rack-cache:
require "rack/cache" require "sinatra" use Rack::Cache get '/' do cache_control :public, :max_age => 36000 sleep 5 "olá" end
Use a configuração :static_cache_control
(veja
[acima]#(controle-de-cache)) para adicionar o cabeçalho de informação
Cache-Control
para arquivos estáticos.
De acordo com a RFC 2616, sua aplicação deve se comportar diferentemente se
o cabeçalho If-Match ou If-None-Match é definido para *
,
dependendo se o recurso requisitado já existe. Sinatra assume que recursos para requisições
seguras (como get) e idempotentes (como put) já existem, enquanto que para
outros recursos (por exemplo requisições post) são tratados como novos
recursos. Você pode mudar esse comportamento passando em uma opção
:new_resource
:
get '/create' do etag '', :new_resource => true Artigo.create erb :novo_artigo end
Se você quer continuar usando um ETag fraco, passe em uma opção
:kind
:
etag '', :new_resource => true, :kind => :weak
Enviando Arquivos¶ ↑
Para retornar os conteúdos de um arquivo como as resposta, você pode usar o
metódo auxiliar send_file
:
get '/' do send_file 'foo.png' end
Também aceita opções:
send_file 'foo.png', :type => :jpg
As opções são:
- filename
- Nome do arquivo a ser usado na respota, o padrão é o nome do arquivo reak
- last_modified
- Valor do cabeçalho Last-Modified, o padrão corresponde ao mtime do arquivo.
- type
- Valor do cabeçalho Content-Type, extraído da extensão do arquivo se inexistente.
- disposition
- Valor do cabeçalho Content-Disposition, valores possíveis: nil (default), :attachment and :inline
- length
- Valor do cabeçalho Content-Length, o padrão corresponde ao tamanho do arquivo.
- status
- Código de status a ser enviado. Útil quando está se enviando um arquivo estático como uma página de erro. Se suportado pelo handler do Rack, outros meios além de transmissão do processo do Ruby serão usados. So você usar esse metódo auxiliar, o Sinatra irá automaticamente lidar com requisições de alcance.
Acessando o Objeto da Requisção¶ ↑
O objeto vindo da requisição pode ser acessado do nível de requsição
(filtros, rotas, manipuladores de erro) através do método
request
:
# app rodando em http://exemplo.com/exemplo get '/foo' do t = %w[text/css text/html application/javascript] request.accept # ['text/html', ' *'] request.accept? 'text/xml' # true request.preferred_type(t) # 'text/html' request.body # corpo da requisição enviado pelo cliente (veja abaixo) request.scheme # "http" request.script_name # "/exemplo" request.path_info # "/foo" request.port # 80 request.request_method # "GET" request.query_string # "" request.content_length # tamanho do request.body request.media_type # tipo de mídia of request.body request.host # "exemplo.com" request.get? # true (metodo similar para outros tipos de requisição) request.form_data? # false request["algum_ param"] # valor do paramêtro 'algum_param'. [] é um atalho para o hash de parametros request.referrer # a referência do cliente ou '/' request.user_agent # agente de usuário (usado por :agent condition) request.cookies # hash dos cookies do browser request.xhr? # isto é uma requisição ajax? request.url # "http://exemplo.com/exemplo/foo" request.path # "/exemplo/foo" request.ip # endereço de IP do cliente request.secure? # false (seria true se a conexão fosse ssl) request.forwarded? # true (se está rodando por um proxy reverso) request.env # raw env hash handed in by Rack end
Algumas opções, como script_name
ou `path_info, podem ser
escritas como:
before { request.path_info = "/" } get "/" do "todas requisições acabam aqui" end
request.body
é uma ES ou um objeo StringIO:
post "/api" do request.body.rewind # em caso de algo já ter lido data = JSON.parse request.body.read "Oi #{data['nome']}!" end
Anexos¶ ↑
Você pode usar o método auxiliar attachment
para dizer ao
navegador que a reposta deve ser armazenada no disco no lugar de ser
exibida no browser:
get '/' do attachment "info.txt" "salve isso!" end
Trabalhando com Data e Hora¶ ↑
O Sinatra oferece um método auxiliar
time_for
que gera um objeto Time do valor dado. É também
possível converter DateTime
, Date
e classes
similares:
get '/' do pass if Time.now > time_for('Dec 23, 2016') "continua no tempo" end
Esse método é usado internamente por expires
,
last_modified
e akin. Você pode portanto facilmente estender o
comportamento desses métodos sobrescrevendo time_for
na sua
aplicação:
helpers do def time_for(valor) case valor when :ontem then Time.now - 24*60*60 when :amanha then Time.now + 24*60*60 else super end end end get '/' do last_modified :ontem expires :amanha "oi" end
Pesquisando por Arquivos de Template¶ ↑
O método auxiliar find_template
é usado para encontrar
arquivos de template para renderizar:
find_template settings.views, 'foo', Tilt[:haml] do |arquivo| puts "pode ser #{arquivo}" end
Isso não é realmente útil. Mas é útil que você possa na verdade sobrescrever esse método para conectar no seu próprio mecanismo de pesquisa. Por exemplo, se você quer ser capaz de usar mais de um diretório de view:
set :views, ['views', 'templates'] helpers do def find_template(views, name, engine, &block) Array(views).each { |v| super(v, name, engine, &block) } end end
Outro exemplo seria utilizando diretórios diferentes para motores (engines) diferentes:
set :views, :sass => 'views/sass', :haml => 'templates', :default => 'views' helpers do def find_template(views, name, engine, &block) _, folder = views.detect { |k,v| engine == Tilt[k] } folder ||= views[:default] super(folder, name, engine, &block) end end
Você pode facilmente embrulhar isso é uma extensão e compartilhar com outras pessoas!
Perceba que find_template
não verifica se o arquivo realmente
existe. Ao invés disso, ele chama o bloco dado para todos os caminhos
possíveis. Isso não significa um problema de perfomance, já que
render
irá usar break
assim que o arquivo é
encontrado. Além disso, as localizações (e conteúdo) de templates serão
guardados na cache se você não estiver rodando no modo de desenvolvimento.
Você deve se lembrar disso se você escrever um método realmente maluco.
Configuração¶ ↑
Rode uma vez, na inicialização, em qualquer ambiente:
configure do ... end
configure do # configurando uma opção set :option, 'value' # configurando múltiplas opções set :a => 1, :b => 2 # o mesmo que `set :option, true` enable :option # o mesmo que `set :option, false` disable :option # você pode também ter configurações dinâmicas com blocos set(:css_dir) { File.join(views, 'css') } end
Rode somente quando o ambiente (APP_ENV
variável de ambiente)
é definida para :production
:
configure :production do ... end
Rode quando o ambiente é definido para :production
ou
:test
:
configure :production, :test do ... end
Você pode acessar essas opções por meio de settings
:
configure do set :foo, 'bar' end get '/' do settings.foo? # => true settings.foo # => 'bar' ... end
Configurando proteção a ataques¶ ↑
O Sinatra está usando Rack::Protection para defender sua aplicação contra ataques oportunistas comuns. Você pode facilmente desabilitar esse comportamento (o que irá abrir sua aplicação à toneladas de vulnerabilidades comuns):
disable :protection
Para pular uma única camada de defesa, defina protection
como
um hash de opções:
set :protection, :except => :path_traversal
Você também pode definir em um array, visando desabilitar uma lista de proteções:
set :protection, :except => [:path_traversal, :session_hijacking]
Por padrão, o Sinatra irá configurar apenas
sessões com proteção se :sessions
tiver sido habilitado. Veja
'Utilizando Sessões'. As vezes
você pode querer configurar sessões “fora” da aplicação do Sinatra, como em config.ru ou com uma instância de
Rack::Builder
separada. Nesse caso, você pode continuar
configurando uma sessão com proteção passando a opção
:session
:
set :protection, :session => true
Configurações Disponíveis¶ ↑
- absolute_redirects
- Se desabilitada, o Sinatra irá permitir redirecionamentos relativos, entretanto, isso não estará conforme a RFC 2616 (HTTP 1.1), que permite apenas redirecionamentos absolutos.
- Habilite se sua aplicação estiver rodando antes de um proxy reverso que não foi configurado corretamente. Note que o método auxiliar url irá continuar produzindo URLs absolutas, a não ser que você passe false como segundo parâmetro.
- Desabilitado por padrão.
- add_charset
- Para tipos Mime o método auxiliar content_type irá automaticamente adicionar a informção de codificação. Você deve adcionar isto no lugar de sobrescrever essa opção: settings.add_charset << "application/foobar"
- app_file
- Caminho para o arquivo principal da aplicação, usado para detectar a raíz do projeto, views e pastas públicas e templates inline.
- bind
- Endereço IP a ser ligado (padrão: 0.0.0.0 ou localhost se seu ambiente está definido como desenvolvimento). Usado apenas para servidor embutido.
- default_encoding
- Codificação assumida caso a mesma seja desconhecida (padrão corresponde a "utf-8").
- dump_errors
- Exibe erros no log.
- environment
- Ambiente atual. O padrão é ENV['APP_ENV'], ou "development" se o primeiro não estiver disponível.
- logging
- Usa o logger.
- lock
- Coloca um bloqueio em torno de cada requisição, executando apenas processamento sob requisição por processo Ruby simultaneamente.
- Habilitado se sua aplicação não for 'thread-safe'. Desabilitado por padrão.
- method_override
- Use a mágica _method para permitir formulários put/delete em navegadores que não oferecem suporte à essas operações.
- mustermann_opts
- Um hash de opções padrão para passar a Mustermann.new quando se está compilado os caminho de roteamento.
- port
- Porta a ser escutada. Usado apenas para servidores embutidos.
- prefixed_redirects
- Inserir ou não inserir request.script_name nos redirecionamentos se nenhum caminho absoluto for dado. Dessa forma redirect '/foo' irá se comportar como redirect to('/foo').
- Desabilitado por padrão.
- protection
- Habilitar ou não proteções a ataques web. Veja a sessão de proteção acima.
- public_dir
- Apelido para public_folder. Veja abaixo.
- public_folder
- Caminho para o diretório de arquivos públicos. Usado apenas se a exibição de arquivos estáticos estiver habilitada (veja a configuração static abaixo). Deduzido da configuração app_file se não for definido.
- quiet
- Desabilita logs gerados pelos comandos de inicio e parada do Sinatra. false por padrão.
- reload_templates
- Se deve ou não recarregar templates entre as requisições. Habilitado no modo de desenvolvimento.
- root
- Caminho para o diretório raíz do projeto. Deduzido da configuração app_file se não for definido.
- raise_errors
- Lança exceções (irá para a aplicação). Habilitado por padrão quando o ambiente está definido para "test, desabilitado em caso contrário.
- run
- Se habilitado, o Sinatra irá lidar com o início do servidor web. Não habilite se estiver usando rackup ou outros meios.
- running
- É o servidor embutido que está rodando agora? Não mude essa configuração!
- server
- Servidor ou listas de servidores para usar o servidor embutido. A ordem indica prioridade, por padrão depende da implementação do Ruby
- server_settings
- Se você estiver usando um servidor web WEBrick, presumidamente para seu ambiente de desenvolvimento, você pode passar um hash de opções para server_settings, tais como SSLEnable ou SSLVerifyClient. Entretanto, servidores web como Puma e Thin não suportam isso, então você pode definir server_settings como um metódo quando chamar configure.
- sessions
- Habilita o suporte a sessões baseadas em cookie usando Rack::Session::Cookie. Veja a seção 'Usando Sessões' para mais informações.
- session_store
- O middleware de sessão Rack usado. O padrão é Rack::Session::Cookie. Veja a sessão 'Usando Sessões' para mais informações.
- show_exceptions
- Mostra um relatório de erros no navegador quando uma exceção ocorrer. Habilitado por padrão quando o ambiente é definido como "development", desabilitado caso contrário.
- Pode também ser definido para :after_handler para disparar um manipulador de erro específico da aplicação antes de mostrar um relatório de erros no navagador.
- static
- Define se o Sinatra deve lidar com o oferecimento de arquivos estáticos.
- Desabilitado quando está utilizando um servidor capaz de fazer isso sozinho.
- Desabilitar irá aumentar a perfomance
- Habilitado por padrão no estilo clássico, desabilitado para aplicações modulares.
- static_cache_control
- Quando o Sinatra está oferecendo arquivos estáticos, definir isso irá adicionar cabeçalhos Cache-Control nas respostas. Usa o método auxiliar cache-control. Desabilitado por padrão.
- Use um array explícito quando estiver definindo múltiplos valores: set :static_cache_control, [:public, :max_age => 300]
- threaded
- Se estiver definido como true, irá definir que o Thin use EventMachine.defer para processar a requisição.
- traps
- Define se o Sinatra deve lidar com sinais do sistema.
- views
- Caminho para o diretório de views. Deduzido da configuração app_file se não estiver definido.
- x_cascade
- Se deve ou não definir o cabeçalho X-Cascade se nenhuma rota combinar. Definido como padrão true
Ambientes¶ ↑
Existem três environments
(ambientes) pré-definidos:
"development"
(desenvolvimento),
"production"
(produção) e
"test"
(teste). Ambientes podem ser definidos
através da variável de ambiente APP_ENV
. O valor padrão é
"development"
. No ambiente
"development"
todos os templates são recarregados
entre as requisições e manipuladores especiais como not_found
e error
exibem relatórios de erros no seu navegador. Nos
ambientes de "production"
e
"test"
, os templates são guardos em cache por
padrão.
Para rodar diferentes ambientes, defina a variável de ambiente
APP_ENV
:
APP_ENV=production ruby minha_app.rb
Você pode usar métodos pré-definidos: development?
,
test?
e production?
para checar a configuração
atual de ambiente:
get '/' do if settings.development? "desenvolvimento!" else "não está em desenvolvimento!" end end
Tratamento de Erros¶ ↑
Manipuladores de erros rodam dentro do mesmo contexto como rotas e filtros
before, o que significa que você pega todos os “presentes” que eles têm
para oferecer, como haml
, erb
, halt
,
etc.
Não Encontrado¶ ↑
Quando uma exceção Sinatra::NotFound
é lançada, ou o código de
status da reposta é 404, o manipulador not_found
é invocado:
not_found do 'Isto está longe de ser encontrado' end
Erro¶ ↑
O manipulador error
é invocado toda a vez que uma exceção é
lançada a partir de um bloco de rota ou um filtro. Note que em
desenvolvimento, ele irá rodar apenas se você tiver definido a opção para
exibir exceções em :after_handler
:
set :show_exceptions, :after_handler
O objeto da exceção pode ser obtido a partir da variável Rack sinatra.error
:
error do 'Desculpe, houve um erro desagradável - ' + env['sinatra.error'].message end
Erros customizados:
error MeuErroCustomizado do 'Então que aconteceu foi...' + env['sinatra.error'].message end
Então, se isso acontecer:
get '/' do raise MeuErroCustomizado, 'alguma coisa ruim' end
Você receberá isso:
Então que aconteceu foi... alguma coisa ruim ```` Alternativamente, você pode instalar um manipulador de erro para um código de status:
ruby error 403 do 'Accesso negado' end
get '/secreto' do 403 end “`
Ou um alcance:
error 400..510 do 'Boom' end
O Sinatra instala os manipuladores especiais
not_found
e error
quando roda sobre o ambiente de
desenvolvimento para exibir relatórios de erros bonitos e informações
adicionais de “debug” no seu navegador.
Rack Middleware¶ ↑
O Sinatra roda no Rack, uma interface padrão mínima para frameworks web em Ruby. Um das capacidades mais interessantes do Rack para desenvolver aplicativos é suporte a “middleware” – componentes que ficam entre o servidor e sua aplicação monitorando e/ou manipulando o request/response do HTTP para prover vários tipos de funcionalidades comuns.
O Sinatra faz construtores pipelines do
middleware Rack facilmente em um nível superior
utilizando o método use
:
require 'sinatra' require 'meu_middleware_customizado' use Rack::Lint use MeuMiddlewareCustomizado get '/ola' do 'Olá mundo' end
A semântica de use
é idêntica aquela definida para a DSL Rack::Builder
(mais frequentemente utilizada para arquivos rackup). Por exemplo, o método
use
aceita múltiplos argumentos/variáveis bem como blocos:
use Rack::Auth::Basic do |usuario, senha| usuario == 'admin' && senha == 'secreto' end
O Rack é distribuido com uma variedade de
middleware padrões para logs, debugs, rotas de URL, autenticação, e
manipuladores de sessão. Sinatra utilizada
muitos desses componentes automaticamente baseando sobre configuração,
então, tipicamente você não tem use
explicitamente.
Você pode achar middlwares utéis em rack, rack-contrib, ou em Rack wiki.
Testando¶ ↑
Testes no Sinatra podem ser escritos utilizando qualquer biblioteca ou framework de teste baseados no Rack. Rack::Test é recomendado:
require 'minha_aplicacao_sinatra' require 'minitest/autorun' require 'rack/test' class MinhaAplicacaoTeste < Minitest::Test include Rack::Test::Methods def app Sinatra::Application end def meu_test_default get '/' assert_equal 'Ola Mundo!', last_response.body end def teste_com_parametros get '/atender', :name => 'Frank' assert_equal 'Olá Frank!', last_response.bodymeet end def test_com_ambiente_rack get '/', {}, 'HTTP_USER_AGENT' => 'Songbird' assert_equal "Você está utilizando o Songbird!", last_response.body end end
NOTA: Se você está usando o Sinatra no estilo modular, substitua `Sinatra::Application' acima com o nome da classe da sua aplicação
Sinatra::Base - Middleware, Bibliotecas e aplicativos modulares¶ ↑
Definir sua aplicação em um nível superior de trabalho funciona bem para
micro aplicativos, mas tem consideráveis incovenientes na construção de
componentes reutilizáveis como um middleware Rack,
metal Rails, bibliotecas simples como um componente de servidor, ou mesmo
extensões Sinatra. A DSL de nível superior polui
o espaço do objeto e assume um estilo de configuração de micro aplicativos
(exemplo: uma simples arquivo de aplicação, diretórios
./public
e ./views
, logs, página de detalhes de
exceção, etc.). É onde o Sinatra::Base
entra em jogo:
require 'sinatra/base' class MinhaApp < Sinatra::Base set :sessions, true set :foo, 'bar' get '/' do 'Ola mundo!' end end
Os métodos disponíveis para subclasses Sinatra::Base
são
exatamente como aqueles disponíveis via a DSL de nível superior. Aplicações
de nível mais alto podem ser convertidas para componentes
Sinatra::Base
com duas modificações:
Seu arquivo deve requerer sinatra/base
ao invés de
sinatra
; caso contrário, todos os métodos DSL do Sinatra são importados para o espaço de nomes
principal.
Coloque as rotas da sua aplicação, manipuladores de erro, filtros e opções
numa subclasse de Sinatra::Base
.
Sinatra::Base
é um quadro branco. Muitas opções são
desabilitadas por padrão, incluindo o servidor embutido. Veja Opções e
Configurações para detalhes de opções disponíveis e seus
comportamentos. Se você quer comportamento mais similiar à quando você
definiu sua aplicação em nível mais alto (também conhecido como estilo
Clássico), você pode usar subclasses de Sinatra::Application
:
require 'sinatra/base' class MinhaApp < Sinatra::Application get '/' do 'Olá mundo!' end end
Estilo Clássico vs. Modular¶ ↑
Ao contrário da crença comum, não há nada de errado com o estilo clássico. Se encaixa com sua aplicação, você não tem que mudar para uma aplicação modular.
As desvantagens principais de usar o estilo clássico no lugar do estilo modular é que você ira ter apenas uma aplicação Sinatra por processo Ruby. Se seu plano é usar mais de uma, mude para o estilo modular. Não há nenhum impedimento para você misturar os estilos clássico e modular.
Se vai mudar de um estilo para outro, você deve tomar cuidado com algumas configurações diferentes:
Configuração | Clássico | Modular | Modular |
---|---|---|---|
app_file | arquivo carregando sinatra | arquivo usando subclasse Sinatra::Base | arquivo usando subclasse Sinatra::Application |
run | $0 == app_file | false | false |
logging | true | false | true |
method_override | true | false | true |
inline_templates | true | false | true |
static | true | File.exist?(public_folder) | true |
Servindo uma Aplicação Modular:¶ ↑
Existem duas opções comuns para começar uma aplicação modular, ativamente
começando com run!
:
# minha_app.rb require 'sinatra/base' class MinhaApp < Sinatra::Base # ... código da aplicação aqui ... # inicie o servidor se o arquivo ruby foi executado diretamente run! if app_file == $0 end
Inicie com with:
ruby minha_app.rb
Ou com um arquivo config.ru
, que permite você usar qualquer
manipulador Rack:
# config.ru (roda com rackup) require './minha_app' run MinhaApp
Rode:
rackup -p 4567
Usando uma Aplicação de Estilo Clássico com um config.ru:¶ ↑
Escreva o arquivo da sua aplicação:
# app.rb require 'sinatra' get '/' do 'Olá mundo!' end
E um config.ru
correspondente:
require './app' run Sinatra::Application
Quando usar um config.ru?¶ ↑
Um arquivo config.ru
é recomendado se:
Você quer lançar com um manipulador Rack diferente (Passenger, Unicorn, Heroku, …).
Você quer usar mais de uma subclasse de Sinatra::Base
. Você
quer usar Sinatra apenas como middleware, mas
não como um “endpoint”.
Não há necessidade de mudar para um config.ru
simplesmente
porque você mudou para o estilo modular, e você não tem que usar o estilo
modular para rodar com um config.ru
.**
Usando Sinatra como Middleware¶ ↑
O Sinatra não é capaz apenas de usar outro middleware Rack, qualquer aplicação Sinatra pode ser adicionada na frente de qualquer “endpoint” Rack como middleware. Esse endpoint pode ser outra aplicação Sinatra, ou qualquer outra aplicação baseada em Rack (Rails/Hanami/Roda/…):
require 'sinatra/base' class TelaLogin < Sinatra::Base enable :sessions get('/login') { haml :login } post('/login') do if params['nome'] == 'admin' && params['senha'] == 'admin' session['nome_usuario'] = params['nome'] else redirect '/login' end end end class MinhaApp < Sinatra::Base # middleware irá rodar filtros before use TelaLogin before do unless session['nome_usuario'] halt "Acesso negado, por favor <a href='/login'>login</a>." end end get('/') { "Olá #{session['nome_usuario']}." } end
Criação de Aplicações Dinâmicas¶ ↑
Às vezes, você quer criar novas aplicações em tempo de execução sem ter que
associa-las a uma constante. Você pode fazer isso com
Sinatra.new
:
require 'sinatra/base' minha_app = Sinatra.new { get('/') { "oi" } } minha_app.run!
Isso leva a aplicação à herdar como um argumento opcional:
# config.ru (roda com rackup) require 'sinatra/base' controller = Sinatra.new do enable :logging helpers MeusHelpers end map('/a') do run Sinatra.new(controller) { get('/') { 'a' } } end map('/b') do run Sinatra.new(controller) { get('/') { 'b' } } end
Isso é especialmente útil para testar extensões do Sinatra ou usar Sinatra na sua própria biblioteca.
Isso também faz o uso do Sinatra como middleware extremamente fácil:
require 'sinatra/base' use Sinatra do get('/') { ... } end run RailsProject::Application
Escopos e Ligação¶ ↑
O escopo que você está atualmente determina quais métodos e varáveis está disponíveis.
Escopo de Aplicação/Classe¶ ↑
Toda aplicação Sinatra corresponde à um
subclasse de Sinatra::Base
. Se você está utilizando a DSL de
nível mais alto (require 'sinatra
), então esta classe é
Sinatra::Application
, caso contrário é a subclasse que você
criou explicitamente. No nível de classe você tem métodos como
get
ou before
, mas você não pode acessar os
objetos request
ou session
, como existe apenas
uma única classe de aplicativo para todas as solicitações.
Opções criadas via set
são métodos a nível de classe:
class MinhaApp < Sinatra::Base # Hey, eu estou no escopo da aplicação! set :foo, 42 foo # => 42 get '/foo' do # Hey, eu não estou mais no escopo da aplicação! end end
Você tem a ligação ao escopo da aplicação dentro:
Do corpo da classe da sua aplicação De métodos definidos por extensões Do
bloco passado a helpers
De Procs/Blocos usados como valor
para set`` Do bloco passado a
Sinatra.new“
Você pode atingir o escopo do objeto (a classe) de duas maneiras:
Por meio do objeto passado aos blocos “configure” (configure { |c|
...}
) settings
de dentro do escopo da requisição
Escopo de Instância/Requisição¶ ↑
Para toda requsição que chega, uma nova instância da classe da sua
aplicação é criada e todos blocos de manipulação rodam nesse escopo. Dentro
desse escopo você pode acessar os objetos request
e
session
ou chamar métodos de renderização como
erb
ou haml
. Você pode acessar o escopo da
aplicação de dentro do escopo da requisição através do método auxiliar
settings
:
class MinhaApp < Sinatra::Base # Hey, eu estou no escopo da aplicação! get '/define_rota/:nome' do # Escopo da requisição para '/define_rota/:nome' @valor = 42 settings.get("/#{params['nome']}") do # Escopo da requisição para "/#{params['nome']}" @valor # => nil (não é a mesma requisição) end "Rota definida!" end end
Você tem a ligação ao escopo da requisição dentro dos:
blocos get, head, post, put, delete, options, patch, link e unlink filtros after e before métodos “helper” (auxiliares) templates/views
Escopo de Delegação¶ ↑
O escopo de delegação apenas encaminha métodos ao escopo da classe.
Entretando, ele não se comporta exatamente como o escopo da classse já que
você não tem a ligação da classe. Apenas métodos marcados explicitamente
para delegação estarão disponíveis e você não compartilha variáveis/estado
com o escopo da classe (leia: você tem um self
diferente).
Você pode explicitamente adicionar delegações de métodos chamando
Sinatra::Delegator.delegate :method_name
.
Você tem a ligação com o escopo delegado dentro:
Da ligação de maior nível, se você digitou require
"sinatra"
De um objeto estendido com o mixin
Sinatra::Delegator
Dê uma olhada no código você mesmo: aqui está Sinatra::Delegator mixin em estendendo o objeto principal.
Linha de Comando¶ ↑
Aplicações Sinatra podem ser executadas diretamente:
ruby minhaapp.rb [-h] [-x] [-q] [-e AMBIENTE] [-p PORTA] [-o HOST] [-s MANIPULADOR]
As opções são:
-h # ajuda -p # define a porta (padrão é 4567) -o # define o host (padrão é 0.0.0.0) -e # define o ambiente (padrão é development) -s # especifica o servidor/manipulador rack (padrão é thin) -x # ativa o bloqueio mutex (padrão é desligado)
Multi-threading¶ ↑
Parafraseando esta resposta no StackOverflow por Konstantin
Sinatra não impõe nenhum modelo de concorrencia, mas deixa isso como responsabilidade do Rack (servidor) subjacente como o Thin, Puma ou WEBrick. Sinatra por si só é thread-safe, então não há nenhum problema se um Rack handler usar um modelo de thread de concorrência. Isso significaria que ao iniciar o servidor, você teria que espeficiar o método de invocação correto para o Rack handler específico. Os seguintes exemplos é uma demonstração de como iniciar um servidor Thin multi-thread:
# app.rb require 'sinatra/base' class App < Sinatra::Base get '/' do 'Olá mundo' end end App.run!
Para iniciar o servidor seria:
thin --threaded start
Requerimentos¶ ↑
As seguintes versões do Ruby são oficialmente suportadas: <dl> <dt>Ruby 2.2</dt> <dd> 2.2 é totalmente suportada e recomendada. Atualmente não existem planos para para o suporte oficial para ela. </dd>
<dt>Rubinius</dt> <dd> Rubinius é oficialmente
suportado (Rubinius >= 2.x). É recomendado rodar gem install
puma
. </dd>
<dt>JRuby</dt> <dd> A útlima versão estável lançada do
JRuby é oficialmente suportada. Não é recomendado usar extensões em C com
o JRuby. É recomendado rodar gem install trinidad
.
</dd> </dl>
Versões do Ruby antes da 2.2.2 não são mais suportadas pelo Sinatra 2.0.
Nós também estamos de olhos em versões futuras do Ruby.
As seguintes implementações do Ruby não são oficialmente suportadas mas sabemos que rodam o Sinatra:
Versões antigas do JRuby e Rubinius Ruby Enterprise Edition MacRuby, Maglev, IronRuby Ruby 1.9.0 e 1.9.1 (mas nós não recomendamos o uso dessas)
Não ser oficialmente suportada significa que se algo quebrar e não estiver nas plataformas suporta, iremos assumir que não é um problema nosso e sim das plataformas.
Nós também rodas nossa IC sobre ruby-head (lançamentos futuros do MRI), mas nós não podemos garantir nada, já que está em constante mudança. Espera-se que lançamentos futuros da versão 2.x sejam totalmente suportadas.
Sinatra deve funcionar em qualquer sistema operacional suportado pela implementação Ruby escolhida.
Se você rodar MacRuby, você deve rodar gem install
control_tower
.
O Sinatra atualmente não roda em Cardinal, SmallRuby, BlueRuby ou qualquer versão do Ruby anterior ao 2.2.
A última versão¶ ↑
Se você gostaria de utilizar o código da última versão do Sinatra, sinta-se livre para rodar a aplicação com o ramo master, ele deve ser estável.
Nós também lançamos pré-lançamentos de gems de tempos em tempos, então você pode fazer:
gem install sinatra --pre
para obter alguma das últimas funcionalidades.
Com Bundler¶ ↑
Se você quer rodar sua aplicação com a última versão do Sinatra usando Bundler é recomendado fazer dessa forma.
Primeiramente, instale o Bundler, se você ainda não tiver:
gem install bundler
Então, no diretório do seu projeto, crie uma Gemfile
:
source 'https://rubygems.org' gem 'sinatra', :github => 'sinatra/sinatra' # outras dependências gem 'haml' # por exemplo, se você usar haml
Perceba que você terá que listar todas suas dependências de aplicação no
Gemfile
. As dependências diretas do Sinatra (Rack e Tilt) irão, entretanto, ser
automaticamente recuperadas e adicionadas pelo Bundler.
Então você pode rodar sua aplicação assim:
bundle exec ruby myapp.rb
Versionando¶ ↑
O Sinatras segue Versionamento Semântico, tanto SemVer como SemVerTag.
Mais¶ ↑
Website do Projeto - Documentação adicional, novidades e links para outros recursos. Contribuir - Encontrou um bug? Precisa de ajuda? Tem um patch? Acompanhar Problemas Twitter Lista de Email Sinatra & Amigos no Slack (consiga um convite) Sinatra Book - Livro de “Receitas” Sinatra Recipes - “Receitas” de contribuições da comunidade Documentação da API para a última release ou para o HEAD atual no Ruby Doc Servidor de CI