stark 0.7.0 → 0.8.0

data/.travis.yml

@@ -0,0 +1,10 @@
+---
+script: rake travis
+before_script:
+- gem install hoe-travis --no-rdoc --no-ri
+- rake travis:before -t
+language: ruby
+rvm:
+- 1.8.7
+- 1.9.2
+- 1.9.3

data/History.txt

@@ -1,3 +1,22 @@
+=== 0.8.0 / 2013-05-22
+
+* 9 new features:
+
+  * Allow circular definitions
+  * Add attr_accessor for structs
+  * Add map and set support
+  * Support structs in lists
+  * Add dotted namespace support
+  * Only serialize fields that are present
+  * Add coercion to/from strings on read
+  * Add coercion and type checking on write
+  * Add Struct#[] and Struct#to_hash
+
+* 2 bugfixes:
+
+  * Fixes to support comments in more places
+  * Catch and log unexpected exceptions
+
 === 0.7.0 / 2013-03-04
 
 * 5 bugfixes:

data/Manifest.txt

@@ -1,18 +1,23 @@
 .autotest
+.gemtest
+.travis.yml
 History.txt
 Manifest.txt
-README.txt
+README.md
 Rakefile
 bin/stark
+examples/README.md
+examples/client.rb
+examples/health.thrift
+examples/server.rb
 lib/stark.rb
 lib/stark/ast.rb
 lib/stark/client.rb
-lib/stark/converters.rb
 lib/stark/exception.rb
-lib/stark/field.rb
 lib/stark/log_transport.rb
 lib/stark/parser.rb
 lib/stark/processor.rb
+lib/stark/protocol_helpers.rb
 lib/stark/raw_parser.rb
 lib/stark/ruby.rb
 lib/stark/struct.rb
@@ -20,6 +25,7 @@ lib/stark/thrift.kpeg
 stark.gemspec
 test/ThriftSpec.thrift
 test/blah.thrift
+test/comments.thrift
 test/gen-rb/profile_constants.rb
 test/gen-rb/profile_types.rb
 test/gen-rb/user_storage.rb
@@ -28,8 +34,16 @@ test/leg.rb
 test/legacy_profile/profile_constants.rb
 test/legacy_profile/profile_types.rb
 test/legacy_profile/user_storage.rb
+test/parsing_error.thrift
 test/profile.thrift
+test/properties.thrift
 test/test_client.rb
+test/test_coerce_strings.rb
+test/test_helper.rb
+test/test_marshal.rb
 test/test_parser.rb
 test/test_ruby.rb
 test/test_server.rb
+test/test_stark.rb
+test/types.thrift
+test/users.thrift

data/README.md

@@ -0,0 +1,164 @@
+# stark [![Build Status](https://travis-ci.org/evanphx/stark.png)](https://travis-ci.org/evanphx/stark)
+
+* http://github.com/evanphx/stark
+
+## DESCRIPTION:
+
+Optimized thrift bindings for ruby.
+
+## FEATURES/PROBLEMS:
+
+* Generates much more straightforward code for thrift clients and servers
+  than the default thrift bindings for ruby.
+
+## SYNOPSIS:
+
+```
+  $ stark service.thrift service.rb
+```
+
+```ruby
+  require 'service'
+```
+
+  OR
+
+```ruby
+  Stark.materialize "service.thrift"
+```
+
+  Use `Service::Client` and
+[`Service::Processor`](http://thrift.apache.org/docs/concepts/) like the default thrift
+  docs describe them.
+
+## REQUIREMENTS:
+
+* thrift gem
+* .thrift files
+
+## INSTALL:
+
+* gem install stark
+
+
+## More in depth
+
+The two main advantages of using Stark are that it allows you to not
+have to convert thrift files ahead of time and the generated Ruby code is of
+higher quality than the output of the Thrift Ruby gem.
+
+### How to
+
+When using `Stark.materialize` on a `.thrift` file, the file gets parsed
+and converted into Ruby code that is available right away for you to
+use.
+
+Lets take this example thrift file:
+
+```
+struct User {
+  1: required i32 id
+  2: string firstName
+  3: string lastName
+}
+
+exception UserNotFound {
+  1: i32 errorCode
+  2: string errorMessage
+}
+
+service GetUser {
+  User fetchUser(1: string email) throws (1: UserNotFound e)
+}
+```
+
+Stark will generate the equivalent of the following code:
+
+```ruby
+class User < Stark::Struct
+  attr_reader :id, :firstName, :lastName
+end
+
+class UserNotFound < Stark::Exception
+  attr_reader :errorCode, :errorMessage
+end
+
+module GetUser
+
+  class Client < Stark::Client
+    def fetchUser(email)
+      # code to make the RPC call, handle errors etc..
+    end
+  end
+
+  class Processor < Stark::Processor
+    def process_fetchUser(seqid, ip, op)
+    end
+  end
+
+end
+```
+
+#### Namespacing
+
+While the generated code above is great, it might conflict with code you
+already have in your application. To avoid conflicts, you can namespace
+your materialized thrift examples.
+
+```ruby
+module MyApp; end
+Stark.materialize "example.thrift", MyApp
+```
+
+The newly generated `GetUser` class is now generated under the provided
+namespace: `MyApp::GetUser`.
+
+Note that materializing a thrift file from within a module or a class
+will still generate the code at the top level unless you specify a
+namespace.
+
+
+### Debugging
+
+Spark will output some valuable (albeit verbose) debugging information
+if you set the `STARK_DEBUG` environment variable.
+
+```
+$ STARK_DEBUG=true ruby code_using_stark.rb
+```
+
+## DEVELOPERS:
+
+After checking out the source, run:
+
+```
+  $ rake newb
+```
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the RDoc.
+
+## LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2013 Evan Phoenix
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -1,8 +1,10 @@
 # -*- ruby -*-
 
-require 'rubygems'
 require 'hoe'
 
+# Don't turn on warnings, output is very ugly w/ generated code
+Hoe::RUBY_FLAGS.sub! /-w/, ''
+
 Hoe.plugin :travis
 Hoe.plugin :gemspec
 Hoe.plugin :git
@@ -11,6 +13,7 @@ Hoe.spec 'stark' do
   developer('Evan Phoenix', 'evan@phx.io')
 
   dependency "thrift", "~> 0.9.0"
+  readme_file = "README.md"
 end
 
 task :parser do

data/bin/stark

@@ -12,12 +12,20 @@ end
 
 ast = Stark::Parser.ast File.read(file)
 
-if out = ARGV.shift
-  out = File.open out, "w"
+if file = ARGV.shift
+  out = File.open file, "w"
 else
   out = STDOUT
 end
 
 ruby = Stark::Ruby.new out
 
-ruby.run ast
+begin
+  ruby.run ast
+rescue
+  if file
+    out.close
+    File.unlink file
+  end
+  raise
+end

data/examples/README.md

@@ -0,0 +1,114 @@
+Building a network service and client with Stark
+================================================
+
+Writing a service with Stark isn't hard. Wiring up the Thrift network stuff is
+a little challenging, but knowing where to start helps.
+
+Running the examples
+--------------------
+
+From the root of the stark repo:
+
+1. `$ ruby -Ilib -Iexamples examples/server.rb &`
+1. `$ ruby -Ilib -Iexamples examples/client.rb`
+
+Write the Thrift IDL
+--------------------
+
+The first thing you need to do is write a definition for your Thrift service.
+Here are some good examples:
+
+* `examples/health.thrift`: a simple service with one procedure and one struct
+* `test/profile.thrift`: a more sophisticated service for user profiles
+* `test/ThriftSpec.thrift`: everything in Thrift, presented concisely 
+
+An example Thrift service
+-------------------------
+
+For the following examples, we'll use this service defintion:
+
+```thrift
+struct Healthcheck {
+  1: bool ok,
+  2: string message
+}
+
+service Health {
+  Healthcheck check()
+}
+```
+
+This defines a service with one message, `check` that returns a `Healthcheck`
+struct.
+
+Write a client
+--------------
+
+Using Stark, you can avoid the need to generate and track sources generated
+from your Thrift IDL. A simple Thrift client looks like this:
+
+```ruby
+require 'thrift'
+require 'stark'
+
+Stark.materialize "examples/health.thrift"
+
+socket    = Thrift::UNIXSocket.new('/tmp/health_sock').tap { |s| s.open }
+transport = Thrift::IOStreamTransport.new socket.to_io, socket.to_io
+proto     = Thrift::BinaryProtocol.new transport
+client    = Health::Client.new proto, proto
+
+result = client.check
+```
+
+For your own purposes, you'll probably use a different kind of socket (one of
+the TCP-based ones) and your client class will be different. You probably won't need to tinker with the transport and protocol until you've got services in
+production.
+
+Write a service
+---------------
+
+A Thrift service using Stark has a lot of symmetry to the client. A simple
+service looks like this:
+
+```ruby
+require 'thrift'
+require 'stark'
+
+Stark.materialize "examples/health.thrift"
+
+class Health::Handler
+
+  def check
+    Healthcheck.new('ok' => true, "message" => "OK")
+  end
+
+end
+
+transport = Thrift::UNIXServerSocket.new '/tmp/health_sock'
+processor = Health::Processor.new Health::Handler.new
+server    = Thrift::SimpleServer.new processor, transport
+server.serve
+```
+
+There are a few more moving parts here. We start off similar, requiring `stark`
+and `thrift`, then dynamically creating the Ruby classes for our service via
+`Stark.materialize`. Next we define a handler class that implements the logic
+of our service. It defines the `check` method from our service. We then create
+a transport and processor for our service and hook it up to a server class
+provided by the `thrift` gem. Calling `serve` starts the server loop.
+
+Not too hard!
+
+Where to go next?
+-----------------
+
+* Read up on [Thrift concepts](http://thrift.apache.org/docs/concepts/), it
+  will come in handy as you implement your own services and clients.
+* Try writing your own service.
+* Lots of people are already implementing HTTP services. Luckily, stark can
+  help you make the transition from HTTP-based services. You can use
+  [stark-http](https://github.com/evanphx/stark-http) to write Thrift clients
+  over HTTP and [stark-rack](https://github.com/evanphx/stark-rack) to
+  implement Thrift services over HTTP.
+

data/examples/client.rb

@@ -0,0 +1,13 @@
+require 'thrift'
+require 'stark'
+
+Stark.materialize "examples/health.thrift"
+
+socket    = Thrift::UNIXSocket.new('/tmp/health_sock').tap { |s| s.open }
+transport = Thrift::IOStreamTransport.new socket.to_io, socket.to_io
+proto     = Thrift::BinaryProtocol.new transport
+client    = Health::Client.new proto, proto
+
+result = client.check
+p [result.ok, result.message]
+

data/examples/health.thrift

@@ -0,0 +1,9 @@
+struct Healthcheck {
+  1: bool ok,
+  2: string message
+}
+
+service Health {
+  Healthcheck check()
+}
+

data/examples/server.rb

@@ -0,0 +1,18 @@
+require 'thrift'
+require 'stark'
+
+Stark.materialize "examples/health.thrift"
+
+class Health::Handler
+
+  def check
+    Healthcheck.new('ok' => true, "message" => "OK")
+  end
+
+end
+
+transport = Thrift::UNIXServerSocket.new '/tmp/health_sock'
+processor = Health::Processor.new Health::Handler.new
+server    = Thrift::SimpleServer.new processor, transport
+server.serve
+