From c0d431d22ee1e2e69338189f9ce5a4b4abc07e6e Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Sat, 10 Jan 2015 04:27:20 +0000 Subject: switch docs + website to olddoc wrongdoc was difficult to maintain because of the tidy-ffi dependency and the HTML5 changes in Darkfish could not be handled well by Tidy. olddoc is superior as it generates leaner HTML which loads faster, requires less scrolling and less processing power to render. Aesthetic comparisons are subjective of course but completely unimportant compared to speed and accessibility. The presence of images and CSS on the old (Darkfish-based) site probably set unreasonable expectations as to my ability and willingness to view such things. No more, the new website is entirely simple HTML which renders well with even the wimpiest browser (hell, olddoc even tries to generate readable raw HTML). --- .document | 1 - .gitignore | 4 ++- .olddoc.yml | 18 +++++++++++ .wrongdoc.yml | 11 ------- DEPLOY | 10 +++---- Documentation/comparison.css | 6 ---- FAQ | 14 ++++----- GNUmakefile | 13 +------- HACKING | 8 ++--- README | 6 ++-- Rakefile | 71 -------------------------------------------- SIGNALS | 6 ++-- Sandbox | 2 +- Static_Files | 2 +- Summary | 0 pkg.mk | 54 +++++++++++---------------------- rainbows.gemspec | 12 ++++---- vs_Unicorn | 16 +++++----- 18 files changed, 76 insertions(+), 178 deletions(-) create mode 100644 .olddoc.yml delete mode 100644 .wrongdoc.yml delete mode 100644 Documentation/comparison.css delete mode 100644 Rakefile delete mode 100644 Summary diff --git a/.document b/.document index e75b6a0..9177b87 100644 --- a/.document +++ b/.document @@ -1,4 +1,3 @@ -ChangeLog DEPLOY FAQ lib/rainbows.rb diff --git a/.gitignore b/.gitignore index 66dea81..00f7d73 100644 --- a/.gitignore +++ b/.gitignore @@ -11,7 +11,7 @@ log/ pkg/ /vendor -/NEWS +/NEWS* /ChangeLog /.manifest /GIT-VERSION-FILE @@ -19,4 +19,6 @@ pkg/ /LATEST tags TAGS +/Summary +/rainbows_1 /lib/rainbows/version.rb diff --git a/.olddoc.yml b/.olddoc.yml new file mode 100644 index 0000000..1e777ea --- /dev/null +++ b/.olddoc.yml @@ -0,0 +1,18 @@ +--- +cgit_url: http://bogomips.org/rainbows.git +git_url: git://bogomips.org/rainbows.git +rdoc_url: http://rainbows.bogomips.org/ +merge_html: + rainbows_1: Documentation/rainbows.1.html + Summary: Documentation/comparison.html +public_email: rainbows-public@bogomips.org +private_email: rainbows@bogomips.org +noindex: +- TODO +- LATEST +- Unicorn +- Unicorn::Configurator +- Unicorn::SocketHelper +- EM +- Revactor +ml_url: http://bogomips.org/rainbows-public/ diff --git a/.wrongdoc.yml b/.wrongdoc.yml deleted file mode 100644 index 82cefb0..0000000 --- a/.wrongdoc.yml +++ /dev/null @@ -1,11 +0,0 @@ ---- -cgit_url: http://bogomips.org/rainbows.git -git_url: git://bogomips.org/rainbows.git -rdoc_url: http://rainbows.bogomips.org/ -changelog_start: v0.97.0 -merge_html: - rainbows_1: Documentation/rainbows.1.html - Summary: Documentation/comparison.html -public_email: rainbows-public@bogomips.org -private_email: rainbows@bogomips.org -ml_url: http://bogomips.org/rainbows-public/ diff --git a/DEPLOY b/DEPLOY index 253a068..1566d43 100644 --- a/DEPLOY +++ b/DEPLOY @@ -13,26 +13,26 @@ processing of the request body as it is being uploaded. In this case, haproxy or any similar (non-request-body-buffering) load balancer should be used to balance requests between different machines. -== nginx proxying to \Rainbows! or Unicorn +== nginx proxying to \Rainbows! or unicorn For high-traffic applications, routing slow actions to \Rainbows! with nginx is recommended as nginx can serve static files faster and nginx -can forward fast actions to Unicorn. +can forward fast actions to unicorn. static files | nginx |--> slow actions --> Rainbows! | - `--> fast actions --> Unicorn + `--> fast actions --> unicorn Be sure to set proxy_buffering off in nginx for "slow actions" -if you have Comet applications (but not for Unicorn). +if you have Comet applications (but not for unicorn). == Denial-of-Service Concerns Since \Rainbows! is designed to talk to slow clients with long-held connections, it may be subject to brute force denial-of-service attacks. -In Unicorn and Mongrel, we've already enabled the "httpready" accept +In unicorn and Mongrel, we've already enabled the "httpready" accept filter for FreeBSD and the TCP_DEFER_ACCEPT option in Linux; but it is still possible to build clients that work around and fool these mechanisms. diff --git a/Documentation/comparison.css b/Documentation/comparison.css deleted file mode 100644 index 82a6012..0000000 --- a/Documentation/comparison.css +++ /dev/null @@ -1,6 +0,0 @@ -/* help to make this look nice would be greatly appreciated */ -.comparison { - margin: 1em; - border: 1px solid; - width: 100%; -} diff --git a/FAQ b/FAQ index cea032b..460aee5 100644 --- a/FAQ +++ b/FAQ @@ -1,10 +1,10 @@ = Frequently Asked Questions about \Rainbows! -=== Why is \Rainbows! a separate project from Unicorn? +=== Why is \Rainbows! a separate project from unicorn? -\Rainbows! is for the odd, corner-case requests that Unicorn is poorly +\Rainbows! is for the odd, corner-case requests that unicorn is poorly suited for. More scalable concurrency models introduce additional -complexity that Unicorn users and developers are uncomfortable with for +complexity that unicorn users and developers are uncomfortable with for the common cases. @@ -15,7 +15,7 @@ models, or are just too lazy to deal with them for the majority of requests we service. -=== Isn't "rainbows" a branch of Unicorn? +=== Isn't "rainbows" a branch of unicorn? That functionality is now in the Revactor model of \Rainbows! However, \Revactor is not recommended since it is dormant @@ -23,7 +23,7 @@ upstream and requires your application (and all its libraries) to cooperate with \Revactor for concurrency. -=== What happened to the "gossamer" branch of Unicorn? +=== What happened to the "gossamer" branch of unicorn? It became the ThreadPool model of \Rainbows! @@ -39,7 +39,7 @@ ease-of-debugging, compatibility, performance, and memory usage. === Should I put \Rainbows! behind nginx to serve slow clients? It is optional. You can still use nginx to route certain requests to -Unicorn and others to \Rainbows! nginx will always outperform +unicorn and others to \Rainbows! nginx will always outperform \Rainbows! in both pure reverse proxy applications and for serving static files, but \Rainbows! is for hosting applications that are more easily-implemented in Ruby than C. @@ -64,7 +64,7 @@ requires a extra {patch}[http://haproxy.1wt.eu/download/patches/]. If you don't need streaming "rack.input", then nginx is a great HTTPS reverse proxy. -Refer to the {Unicorn FAQ}[http://unicorn.bogomips.org/FAQ.html] on how +Refer to the {unicorn FAQ}[http://unicorn.bogomips.org/FAQ.html] on how to ensure redirects go to "https://" URLs. diff --git a/GNUmakefile b/GNUmakefile index 3001281..0eb88da 100644 --- a/GNUmakefile +++ b/GNUmakefile @@ -2,23 +2,16 @@ all:: # RSYNC_DEST := rubyforge.org:/var/www/gforge-projects/rainbows RSYNC_DEST := rainbows.bogomips.org:/srv/rainbows -rfproject := rainbows rfpackage := rainbows +PLACEHOLDERS := rainbows_1 Summary man-rdoc: man html $(MAKE) -C Documentation comparison.html - for i in $(man1_rdoc); do echo > $$i; done doc:: man-rdoc include pkg.mk -ifneq ($(VERSION),) -release:: - $(RAKE) publish_news VERSION=$(VERSION) - $(RAKE) fm_update VERSION=$(VERSION) -endif base_bins := rainbows bins := $(addprefix bin/, $(base_bins)) -man1_rdoc := $(addsuffix _1, $(base_bins)) man1_bins := $(addsuffix .1, $(base_bins)) man1_paths := $(addprefix man/man1/, $(man1_bins)) @@ -30,10 +23,6 @@ man html: pkg_extra += $(man1_paths) lib/rainbows/version.rb -doc:: - cat Documentation/comparison.css >> doc/rdoc.css - $(RM) $(man1_rdoc) - lib/rainbows/version.rb: GIT-VERSION-FILE all:: test diff --git a/HACKING b/HACKING index 946887d..27c87a4 100644 --- a/HACKING +++ b/HACKING @@ -6,10 +6,8 @@ All tests are written in POSIX shell. See README file in the t/ directory. === Documentation -We use RDoc 3.9.x with Darkfish for documentation as much as possible, -if you're on Ruby 1.8 you want to install the latest "rdoc" gem. Due to -the lack of RDoc-to-manpage converters we know about, we're writing -manpages in Markdown and converting to troff/HTML with Pandoc. +Due to the lack of RDoc-to-manpage converters we know about, we're +writing manpages in Markdown and converting to troff/HTML with Pandoc. Please wrap documentation at 72 characters-per-line or less (long URLs are exempt) so it is comfortably readable from terminals. @@ -48,7 +46,7 @@ Please Cc: everyone on replies, as not everyone is subscribed. In order to build the gem, you must install the following components: - * wrongdoc + * olddoc (RubyGem) * pandoc You can build the Unicorn gem with the following command: diff --git a/README b/README index 727a0a7..174253b 100644 --- a/README +++ b/README @@ -1,11 +1,11 @@ -= Rainbows! - Unicorn for sleepy apps and slow clients += Rainbows! - unicorn for sleepy apps and slow clients \Rainbows! is an HTTP server for sleepy Rack applications. It is based on -Unicorn, but designed to handle applications that expect long +unicorn, but designed to handle applications that expect long request/response times and/or slow clients. For Rack applications not heavily bound by slow external network -dependencies, consider Unicorn instead as it simpler and easier to +dependencies, consider unicorn instead as it simpler and easier to debug. If you're on a small system, or write extremely tight and reliable code diff --git a/Rakefile b/Rakefile deleted file mode 100644 index 58de7fb..0000000 --- a/Rakefile +++ /dev/null @@ -1,71 +0,0 @@ -# -*- encoding: binary -*- -autoload :Gem, 'rubygems' -autoload :Tempfile, 'tempfile' -require 'wrongdoc' - -cgit_url = Wrongdoc.config[:cgit_url] -git_url = Wrongdoc.config[:git_url] - -desc "read news article from STDIN and post to rubyforge" -task :publish_news do - require 'rubyforge' - spec = Gem::Specification.load('rainbows.gemspec') - tmp = Tempfile.new('rf-news') - _, subject, body = `git cat-file tag v#{spec.version}`.split(/\n\n/, 3) - tmp.puts subject - tmp.puts - tmp.puts spec.description.strip - tmp.puts "" - tmp.puts "* #{spec.homepage}" - tmp.puts "* #{spec.email}" - tmp.puts "* #{git_url}" - tmp.print "\nChanges:\n\n" - tmp.puts body - tmp.flush - system(ENV["VISUAL"], tmp.path) or abort "#{ENV["VISUAL"]} failed: #$?" - msg = File.readlines(tmp.path) - subject = msg.shift - blank = msg.shift - blank == "\n" or abort "no newline after subject!" - subject.strip! - body = msg.join("").strip! - - rf = RubyForge.new.configure - rf.login - rf.post_news('rainbows', subject, body) -end - -desc "post to FM" -task :fm_update do - require 'net/http' - require 'net/netrc' - require 'json' - version = ENV['VERSION'] or abort "VERSION= needed" - uri = URI.parse('https://freecode.com/projects/rainbows/releases.json') - rc = Net::Netrc.locate('rainbows-fm') or abort "~/.netrc not found" - api_token = rc.password - _, subject, body = `git cat-file tag v#{version}`.split(/\n\n/, 3) - tmp = Tempfile.new('fm-changelog') - tmp.puts subject - tmp.puts - tmp.puts body - tmp.flush - system(ENV["VISUAL"], tmp.path) or abort "#{ENV["VISUAL"]} failed: #$?" - changelog = File.read(tmp.path).strip - - req = { - "auth_code" => api_token, - "release" => { - "tag_list" => "Stable", - "version" => version, - "changelog" => changelog, - }, - }.to_json - if ! changelog.strip.empty? && version =~ %r{\A[\d\.]+\d+\z} - Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http| - p http.post(uri.path, req, {'Content-Type'=>'application/json'}) - end - else - warn "not updating freshmeat for v#{version}" - end -end diff --git a/SIGNALS b/SIGNALS index b761ae5..e53c3e4 100644 --- a/SIGNALS +++ b/SIGNALS @@ -5,7 +5,7 @@ the signals Rainbows! uses internally to communicate with the worker processes are documented here as well. With the exception of TTIN/TTOU, signal handling matches the behavior of and {nginx}[http://nginx.net/] so it should be possible to easily share process management scripts -between \Rainbows!, Unicorn and nginx. +between \Rainbows!, unicorn and nginx. === Master Process @@ -60,7 +60,7 @@ automatically respawned. * USR1 - Reopen all logs owned by the worker process. See Unicorn::Util.reopen_logs for what is considered a log. - Unlike Unicorn, log files are reopened immediately in \Rainbows! + Unlike unicorn, log files are reopened immediately in \Rainbows! since worker processes are likely to be serving multiple clients simutaneously, we can't wait for all of them to finish. @@ -68,7 +68,7 @@ automatically respawned. You may replace a running instance of rainbows with a new one without losing any incoming connections. Doing so will reload all of your -application code, Unicorn/Rainbows! config, Ruby executable, and all +application code, unicorn/Rainbows! config, Ruby executable, and all libraries. The only things that will not change (due to OS limitations) are: diff --git a/Sandbox b/Sandbox index 56dd29f..fccb1ed 100644 --- a/Sandbox +++ b/Sandbox @@ -1,6 +1,6 @@ = Tips for using \Rainbows! with Sandbox installation tools -Most {tips for Unicorn}[http://unicorn.bogomips.org/Sandbox.html] +Most {tips for unicorn}[http://unicorn.bogomips.org/Sandbox.html] for Bundler and Isolate apply to \Rainbows! as well. == TLDR (Bundler) diff --git a/Static_Files b/Static_Files index 3ced433..bbc47a8 100644 --- a/Static_Files +++ b/Static_Files @@ -10,7 +10,7 @@ to simplify your deployments and only deploy one server? == {sendfile}[http://rubygems.org/gems/sendfile] RubyGem To enable the "sendfile" gem, just make sure you have 1.1.0 or later and -"require" it in your \Rainbows!/Unicorn config file (not your Rack +"require" it in your \Rainbows!/unicorn config file (not your Rack config.ru): require 'sendfile' # that's it! nothing else to do diff --git a/Summary b/Summary deleted file mode 100644 index e69de29..0000000 diff --git a/pkg.mk b/pkg.mk index 4cd5bef..3c2e910 100644 --- a/pkg.mk +++ b/pkg.mk @@ -1,7 +1,8 @@ RUBY = ruby RAKE = rake RSYNC = rsync -WRONGDOC = wrongdoc +OLDDOC = olddoc +RDOC = rdoc GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE @./GIT-VERSION-GEN @@ -48,10 +49,10 @@ else build: endif -pkg_extra += GIT-VERSION-FILE NEWS ChangeLog LATEST -ChangeLog: GIT-VERSION-FILE .wrongdoc.yml - $(WRONGDOC) prepare -NEWS LATEST: ChangeLog +pkg_extra += GIT-VERSION-FILE NEWS LATEST +NEWS: GIT-VERSION-FILE .olddoc.yml + $(OLDDOC) prepare +LATEST: NEWS manifest: $(RM) .manifest @@ -63,28 +64,20 @@ manifest: cmp $@+ $@ || mv $@+ $@ $(RM) $@+ -doc:: .document .wrongdoc.yml $(pkg_extra) +doc:: .document .olddoc.yml $(pkg_extra) $(PLACEHOLDERS) -find lib -type f -name '*.rbc' -exec rm -f '{}' ';' -find ext -type f -name '*.rbc' -exec rm -f '{}' ';' $(RM) -r doc - $(WRONGDOC) all + $(RDOC) -f oldweb + $(OLDDOC) merge install -m644 COPYING doc/COPYING + install -m644 NEWS doc/NEWS + install -m644 NEWS.atom.xml doc/NEWS.atom.xml install -m644 $(shell LC_ALL=C grep '^[A-Z]' .document) doc/ ifneq ($(VERSION),) pkggem := pkg/$(rfpackage)-$(VERSION).gem pkgtgz := pkg/$(rfpackage)-$(VERSION).tgz -release_notes := release_notes-$(VERSION) -release_changes := release_changes-$(VERSION) - -release-notes: $(release_notes) -release-changes: $(release_changes) -$(release_changes): - $(WRONGDOC) release_changes > $@+ - $(VISUAL) $@+ && test -s $@+ && mv $@+ $@ -$(release_notes): - $(WRONGDOC) release_notes > $@+ - $(VISUAL) $@+ && test -s $@+ && mv $@+ $@ # ensures we're actually on the tagged $(VERSION), only used for release verify: @@ -120,23 +113,9 @@ $(pkgtgz): manifest fix-perms package: $(pkgtgz) $(pkggem) -test-release:: verify package $(release_notes) $(release_changes) - # make tgz release on RubyForge - @echo rubyforge add_release -f \ - -n $(release_notes) -a $(release_changes) \ - $(rfproject) $(rfpackage) $(VERSION) $(pkgtgz) - @echo gem push $(pkggem) - @echo rubyforge add_file \ - $(rfproject) $(rfpackage) $(VERSION) $(pkggem) -release:: verify package $(release_notes) $(release_changes) - # make tgz release on RubyForge - rubyforge add_release -f -n $(release_notes) -a $(release_changes) \ - $(rfproject) $(rfpackage) $(VERSION) $(pkgtgz) +release:: verify package # push gem to RubyGems.org gem push $(pkggem) - # in case of gem downloads from RubyForge releases page - rubyforge add_file \ - $(rfproject) $(rfpackage) $(VERSION) $(pkggem) else gem install-gem: GIT-VERSION-FILE $(MAKE) $@ VERSION=$(GIT_VERSION) @@ -154,8 +133,6 @@ ifneq ($(RSYNC_DEST),) publish_doc: -git set-file-times $(MAKE) doc - find doc/images -type f | \ - TZ=UTC xargs touch -d '1970-01-01 00:00:06' doc/rdoc.css $(MAKE) doc_gz $(RSYNC) -av doc/ $(RSYNC_DEST)/ git ls-files | xargs touch @@ -163,7 +140,7 @@ endif # Create gzip variants of the same timestamp as the original so nginx # "gzip_static on" can serve the gzipped versions directly. -doc_gz: docs = $(shell find doc -type f ! -regex '^.*\.\(gif\|jpg\|png\|gz\)$$') +doc_gz: docs = $(shell find doc -type f ! -regex '^.*\.gz$$') doc_gz: for i in $(docs); do \ gzip --rsyncable -9 < $$i > $$i.gz; touch -r $$i $$i.gz; done @@ -171,5 +148,10 @@ check-warnings: @(for i in $$(git ls-files '*.rb'| grep -v '^setup\.rb$$'); \ do $(RUBY) -d -W2 -c $$i; done) | grep -v '^Syntax OK$$' || : +ifneq ($(PLACEHOLDERS),) +$(PLACEHOLDERS): + echo olddoc_placeholder > $@ +endif + .PHONY: all .FORCE-GIT-VERSION-FILE doc test $(test_units) manifest .PHONY: check-warnings diff --git a/rainbows.gemspec b/rainbows.gemspec index 5aa2dce..a2512b3 100644 --- a/rainbows.gemspec +++ b/rainbows.gemspec @@ -1,8 +1,8 @@ # -*- encoding: binary -*- ENV["VERSION"] or abort "VERSION= must be specified" manifest = File.readlines('.manifest').map! { |x| x.chomp! } -require 'wrongdoc' -extend Wrongdoc::Gemspec +require 'olddoc' +extend Olddoc::Gemspec name, summary, title = readme_metadata Gem::Specification.new do |s| @@ -10,16 +10,14 @@ Gem::Specification.new do |s| s.version = ENV["VERSION"].dup s.authors = ["#{name} hackers"] - s.date = Time.now.utc.strftime('%Y-%m-%d') s.description = readme_description s.email = %q{rainbows-public@bogomips.org} s.executables = %w(rainbows) s.extra_rdoc_files = extra_rdoc_files(manifest) s.files = manifest - s.homepage = Wrongdoc.config[:rdoc_url] + s.homepage = Olddoc.config['rdoc_url'] s.summary = summary s.rdoc_options = rdoc_options - s.rubyforge_project = %q{rainbows} # we want a newer Rack for a valid HeaderHash#each s.add_dependency(%q, ['~> 1.1']) @@ -27,13 +25,13 @@ Gem::Specification.new do |s| # kgio 2.5 has kgio_wait_* methods that take optional timeout args s.add_dependency(%q, ['~> 2.5']) - # we need Unicorn for the HTTP parser and process management + # we need unicorn for the HTTP parser and process management # we need unicorn 4.8.0+ since we depend on undocumented/unsupported # unicorn internals. s.add_dependency(%q, ["~> 4.8"]) s.add_development_dependency(%q, "~> 3.1") - s.add_development_dependency(%q, "~> 1.8") + s.add_development_dependency(%q, "~> 1.0") # optional runtime dependencies depending on configuration # see t/test_isolate.rb for the exact versions we've tested with diff --git a/vs_Unicorn b/vs_Unicorn index 67e4250..6f910a7 100644 --- a/vs_Unicorn +++ b/vs_Unicorn @@ -1,11 +1,11 @@ -= \Rainbows! is like Unicorn, but Different... += \Rainbows! is like unicorn, but Different... -While \Rainbows! depends on Unicorn for its process/socket management, +While \Rainbows! depends on unicorn for its process/socket management, HTTP parser and configuration language; \Rainbows! is more ambitious. == Architectural Diagrams -=== Unicorn uses a 1:1 mapping of processes to clients +=== unicorn uses a 1:1 mapping of processes to clients unicorn master \_ unicorn worker[0] @@ -52,16 +52,16 @@ In both cases, workers share common listen sockets with the master and pull connections off the listen queue only if the worker has resources available. -== Differences from Unicorn +== Differences from unicorn -* log rotation is handled immediately in \Rainbows! whereas Unicorn has +* log rotation is handled immediately in \Rainbows! whereas unicorn has the luxury of delaying it until the current request is finished processing to prevent log entries for one request to be split across files. * load balancing between workers is imperfect, certain worker processes may be servicing more requests than others so it is important to not - set +worker_connections+ too high. Unicorn worker processes can never + set +worker_connections+ too high. unicorn worker processes can never be servicing more than one request at once. * speculative, non-blocking accept() is not used, this is to help @@ -72,10 +72,10 @@ available. * Less heavily-tested and inherently more complex. -== Similarities with Unicorn +== Similarities with unicorn While some similarities are obvious (we depend on and subclass off -Unicorn code), some things are not: +unicorn code), some things are not: * Does not attempt to accept() connections when pre-configured limits are hit (+worker_connections+). This will first help balance load -- cgit v1.2.3-24-ge0c7