agoo 2.15.10 → 2.15.11

data/misc/rails.md

@@ -0,0 +1,174 @@
+# Rails with Agoo
+
+Agoo gives Rails a performance boost. It's easy to use Agoo with Rails. Start
+with a Rails project. Something simple.
+
+```
+$ rails new blog
+$ rails g scaffold User
+$ rails db:migrate
+```
+
+Now run it with Agoo.
+
+```
+$ rackup -r agoo -s agoo
+```
+
+Or for an extra boost on a machine with multiple cores fire up Agoo with
+multiple workers. The optimium seems to be about one worker per hyperthread or
+two per core.
+
+```
+$ rackup -r agoo -s agoo -O wc=12
+```
+
+What you should see is a faster Rails. Requests to something like
+`http://localhost:9292/users/1` should be several times faster and asset
+fetches should be 8000 times faster. Here are some benchmark runs using the
+[perfer](https://github.com/ohler55/perfer) benchmark tool.
+
+It is easy to push Rails too hard and watch the latency climb. To avoid that
+the number of open connections use is adjusted according to how well the
+server and Rails can handle the load. A balance where the latency is as close
+to the best attainable is used and the throughput is maximized for that
+latency is used in all cases.
+
+All benchmarks were run on a 6 core i7-8700 system with 16GB of memory. The
+driver, `perfer` was run on a separate machine to allow Rails and the web
+server full use of the benchmark machine.
+
+### With Rails managed objects
+
+For the benchmarks a blank `User` object is created using a browser. The a
+fetch is performed repeatedly on that object.
+
+##### With Rails and the default Puma server.
+
+```
+$ perfer -t 1 -c 1 -b 1 192.168.1.11:9292 -p /users/1 -d 10
+Benchmarks for:
+  URL:                192.168.1.11:9292/users/1
+  Threads:            1
+  Connections/thread: 1
+  Duration:           10.0 seconds
+  Keep-Alive:         false
+Results:
+  Throughput:         41 requests/second
+  Latency:            23.612 +/-5.111 msecs (and stdev)
+```
+
+##### Now the same request with Agoo in non-clustered mode.
+
+```
+$ perfer -t 2 -k -c 4 -b 1 192.168.1.11:9292 -p /users/1 -d 10
+Benchmarks for:
+  URL:                192.168.1.11:9292/users/1
+  Threads:            2
+  Connections/thread: 4
+  Duration:           5.0 seconds
+  Keep-Alive:         true
+Results:
+  Throughput:         279 requests/second
+  Latency:            28.608 +/-3.497 msecs (and stdev)
+```
+
+Agoo was able to handle 8 concurrent connections and still maintain the
+latency target of under 30 millisecond. Throughput with Agoo was also 7 times
+greater. Most of the time spent with both Agoo and Puma is most likely in
+Rails and Rackup so lets try Agoo in cluster mode with the application is
+stateless.
+
+##### Now the same request with Agoo in clustered mode.
+
+```
+$ perfer -t 2 -k -c 20 -b 1 192.168.1.11:9292 -p /users/1 -d 10
+Benchmarks for:
+  URL:                192.168.1.11:9292/users/1
+  Threads:            2
+  Connections/thread: 20
+  Duration:           5.0 seconds
+  Keep-Alive:         true
+Results:
+  Throughput:         1476 requests/second
+  Latency:            27.051 +/-11.107 msecs (and stdev)
+```
+
+Another 5x boost in throughput. That make Agoo in cluster mode 36 times faster
+than the default Puma. In all fairness, Puma can be put into clustered mode as
+well using a custom configuration file. If anyone would like to provide
+formula for running Puma at optimum please let me know or create a PR for how
+to run it more effectively.
+
+### Fetching static assets
+
+Rails likes to be in charge and is responsible for serving static assets. Some
+servers such as Agoo offer an option to bypass Rails handling of static
+assets. Allowing static assets to be loaded directly means CSS, HTML, images,
+Javascript, and other static files load quickly so that web sites are more
+snappy even when more than a handful of users are connected.
+
+##### Rails with the default Puma server loading a static asset.
+```
+$ perfer -t 2 -k -c 1 -b 1 192.168.1.11:9292 -p /robots.txt -d 10
+Benchmarks for:
+  URL:                192.168.1.11:9292/robots.txt
+  Threads:            2
+  Connections/thread: 1
+  Duration:           10.0 seconds
+  Keep-Alive:         true
+Results:
+  Throughput:         79 requests/second
+  Latency:            25.027 +/-7.800 msecs (and stdev)
+```
+
+Well, Rails with Puma handles almost twice as as many request as it does for
+Ruby processing of managed object calls. Note that Puma was able to handle 2
+concurrent connections without degradation of the latency.
+
+##### Rails with Agoo loading a static asset in non-clustered mode.
+```
+$ perfer -t 2 -k -c 40 -b 2 192.168.1.11:9292 -p /robots.txt -d 10
+Benchmarks for:
+  URL:                192.168.1.11:9292/robots.txt
+  Threads:            2
+  Connections/thread: 40
+  Duration:           5.0 seconds
+  Keep-Alive:         true
+Results:
+  Throughput:         500527 requests/second
+  Latency:            0.292 +/-0.061 msecs (and stdev)
+```
+
+Wow, more than 6000 times faster and the latency drops from 25 milliseconds to
+a fraction of a millisecond. There is a reason for that. Agoo looks at the
+`Rails.configuration.assets.paths` variable and sets up a bypass to load those
+files directly using the same approach as Rails. Ruby is no longer has to deal
+with basic file serving but can be relogated to taking care of business. It
+also means tha no Ruby objects are created for serving static assets.
+
+Now how about Agoo in clustered mode.
+
+##### Rails with Agoo loading a static asset in clustered mode.
+```
+$ perfer -t 2 -k -c 40 -b 2 192.168.1.11:9292 -p /robots.txt -d 10
+Benchmarks for:
+  URL:                192.168.1.11:9292/robots.txt
+  Threads:            2
+  Connections/thread: 40
+  Duration:           5.0 seconds
+  Keep-Alive:         true
+Results:
+  Throughput:         657777 requests/second
+  Latency:            0.223 +/-0.073 msecs (and stdev)
+```
+
+A bit faster but not that much over the non-clustered Agoo. The limiting
+factor with static assets is the network. Agoo handles 80 concurrent
+connections at the same latency as one.
+
+### Summary
+
+Benchmarks are not everything but if they are an important consideration when
+selecting a web server for Rails or Rack then Agoo clearly has an advantage
+over the Rack and Rails default.

data/misc/song.md

@@ -0,0 +1,268 @@
+# GraphQL with a Song
+
+You've may have heard developer singing praises about how wonderful GraphQL
+is. Maybe you thought it was looking into. I like to learn new technologies by
+using them so this article is a simple example of using GraphQL.
+
+GraphQL is a language for describing an applicaiton API. It holds a similar
+position in the development stack as a REST API but with more
+flexibility. Unlike REST, GraphQL allows response formats and content to be
+specified by the client. Just as SQL `SELECT` statements allow query results
+to be specified, GraphQL allows returned JSON data structure to be
+specified. Following the SQL analogy GraphQL does not provide a `WHERE` clause
+but identifies fields on application objects that should provide the data for
+the response.
+
+GraphQL, as the name suggests models APIs as if the application is a graph of
+data. While that description may not be how you have viewed your application
+it is a model used in most systems. If your application is object based then
+the objects refer to other objects. These object-method-object define a
+graph. Data that can be represented by JSON is a graph as JSON is just a
+directed graph. Thinking about the application as presenting a graph model
+through the API will make GraphQL much easier to understand.
+
+## Consider the Application
+
+Enough of the abstract. Lets get down to actually building an application that
+uses GraphQL by starting with a definition of the data model or the
+graph. Last year I picked up a new hobby. I'm learning to play the electric
+upright bass and about music so a music related example came to mind when
+coming up with and example.
+
+Keeping it simple the object types are __Artist__ and __Song__. __Artists__
+have multiple __Song__ and a __Song__ is associate with an __Artist__. Each
+object type has attributes such as a `name`. Pretty basic and simple.
+
+## Define the API
+
+GraphQL uses SDL (Schema Definition Language) which is sometimes refered to as
+"type system definition language" in the GraphQL specification. GraphQL types
+can, in theory be defined in any language but most common language agnostic
+language is SDL so lets use SDL to define the API.
+
+```
+type Artist {
+  name: String!
+  songs: [Song]
+  origin: [String]
+}
+
+type Song {
+  name: String!
+  artist: Artist
+  duration: Int
+  release: String
+}
+```
+
+Pretty easy to understand. An __Artist__ has a `name` that is a `String`,
+`songs` that is an array of __Song__ objects, and `origin` which is a `String`
+array. __Song__ is similar but with one odd field. The `release` field should
+be a time or date type but GraphQL does not have that type defined as a core
+type. To be completely portable between any GraphQL implementation a `String`
+is used. The GraphQL implemenation we will use as added the `Time` type so
+lets change the __Song__ definition so that the `release` field is a `Time`
+type. The returned value will be a `String` but by setting the type to `Time`
+we document the API more accurately.
+
+```
+  release: Time
+```
+
+The last step is to describe how to get one or more of the objects. This is
+referred to as the root or for queries the query root. Our root will have just
+one field or method called `artist` and will require an artist `name`.
+
+```
+type Query {
+  artist(name: String!): Artist
+}
+```
+
+## Writing the Application
+
+Ruby will be used write the application. There is more than one implemenation
+of a GraphQL server for Ruby. Some approachs require the SDL above to be
+translated into a Ruby equivalent. [Agoo](https://github.com/ohler55/agoo)
+uses the SDL defintion as it is and the Ruby code is plain vanilla Ruby so
+that will be used for this example.
+
+By having the Ruby class names match the GraphQL type names we keep things
+simple. Note that the Ruby classes match the GraphQL types.
+
+```ruby
+class Artist
+  attr_reader :name
+  attr_reader :songs
+  attr_reader :origin
+
+  def initialize(name, origin)
+    @name = name
+    @songs = []
+    @origin = origin
+  end
+
+  def song(args={})
+    @songs[args['name']]
+  end
+
+  # Only used by the Song to add itself to the artist.
+  def add_song(song)
+    @songs << song
+  end
+end
+
+class Song
+  attr_reader :name     # string
+  attr_reader :artist   # reference
+  attr_reader :duration # integer
+  attr_reader :release  # time
+
+  def initialize(name, artist, duration, release)
+    @name = name
+    @artist = artist
+    @duration = duration
+    @release = release
+    artist.add_song(self)
+  end
+end
+```
+
+Method match fields in the Ruby classes. Note the method all have
+either no arguments or `args={}`. This is what the GraphQL APIs expect
+and the [Agoo](https://github.com/ohler55/agoo) GraphQL implementation
+follows suit. [Agoo](https://github.com/ohler55/agoo) offers
+additional options that are available based on the method
+signature. If a method signature is `(args, req)` or `(args, req,
+plan)` then the request object is included. The plan, if included, is
+an object that can be queried for information about the query. (It has
+not been implemented as of version 2.12.0.)
+
+The `initialize` methods are used to set up the data for this example
+as we will see shortly.
+
+The query root class als needs to be defined. Note the `artist` method which
+matches the SDL `Query` root type. An `attr_reader` for `artists` was also
+added. That would be exposed to the API simply by adding that field to the
+`Query` type in the SDL document.
+
+```ruby
+class Query
+  attr_reader :artists
+
+  def initialize(artists)
+    @artists = artists
+  end
+
+  def artist(args={})
+    @artists[args['name']]
+  end
+end
+```
+
+The GraphQL root, not to be confused with the query root sites above the query
+root. GraphQL defines it to optionally have three field. The Ruby class in
+this case implements on the `query` field. The initializer loads up some data
+for an Indie band from New Zealand I like to listen to.
+
+```ruby
+class Schema
+  attr_reader :query
+  attr_reader :mutation
+  attr_reader :subscription
+
+  def initialize()
+    # Set up some data for testing.
+    artist = Artist.new('Fazerdaze', ['Morningside', 'Auckland', 'New Zealand'])
+    Song.new('Jennifer', artist, 240, Time.utc(2017, 5, 5))
+    Song.new('Lucky Girl', artist, 170, Time.utc(2017, 5, 5))
+    Song.new('Friends', artist, 194, Time.utc(2017, 5, 5))
+    Song.new('Reel', artist, 193, Time.utc(2015, 11, 2))
+    @artists = {artist.name => artist}
+
+    @query = Query.new(@artists)
+  end
+end
+```
+
+The final hookup is implemenation specific. For
+[Agoo](https://github.com/ohler55/agoo) the server is initialized to include a
+handler for the `/graphql` HTTP request path ad then it is started.
+
+```
+Agoo::Server.init(6464, 'root', thread_count: 1, graphql: '/graphql')
+Agoo::Server.start()
+```
+
+The GraphQL implementation is then configured with the SDL defined earlier
+(`$songs_sdl`) and then the appliation sleeps while the server processes
+requests.
+
+```
+Agoo::GraphQL.schema(Schema.new) {
+  Agoo::GraphQL.load($songs_sdl)
+}
+sleep
+```
+
+The code for this example is in (https://github.com/ohler55/agoo/example/graphql/song.rb).
+
+## Using the API
+
+A web broswer can be used to try out the API as can `curl`.
+
+The GraphQL query to try looks like the following.
+
+```
+{
+  artist(name:"Fazerdaze") {
+    name
+    songs{
+      name
+      duration
+    }
+  }
+}
+```
+
+The query asks for the __Artist__ named `Frazerdaze` and returns the `name` and `songs` in a JSON document. For each __Song__ the `name` and `duration` of the __Song__ is returned in a JSON object for each __Song__. The output should look like this.
+
+```
+{
+  "data":{
+    "artist":{
+      "name":"Fazerdaze",
+      "songs":[
+        {
+          "name":"Jennifer",
+          "duration":240
+        },
+        {
+          "name":"Lucky Girl",
+          "duration":170
+        },
+        {
+          "name":"Friends",
+          "duration":194
+        },
+        {
+          "name":"Reel",
+          "duration":193
+        }
+      ]
+    }
+  }
+}
+```
+
+After getting rid of the optional whitespace in the query an HTTP GET made
+with curl should return that content.
+
+```
+curl -w "\n" 'localhost:6464/graphql?query=\{artist(name:"Fazerdaze")\{name,songs\{name,duration\}\}\}&indent=2'
+```
+
+Try changing the query and replace `duration` with `release` and not the
+conversion of the Ruby Time to a JSON string.
+
+Hope you enjoyed the example. Now you can sing the GraphQL song.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: agoo
 version: !ruby/object:Gem::Version
-  version: 2.15.10
+  version: 2.15.11
 platform: ruby
 authors:
 - Peter Ohler
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-14 00:00:00.000000000 Z
+date: 2024-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -41,6 +41,13 @@ extra_rdoc_files:
 - README.md
 - CHANGELOG.md
 - LICENSE
+- misc/flymd.md
+- misc/glue.md
+- misc/optimize.md
+- misc/push.md
+- misc/rails.md
+- misc/song.md
+- misc/glue-diagram.svg
 files:
 - CHANGELOG.md
 - LICENSE
@@ -150,6 +157,13 @@ files:
 - lib/agoo/graphql/type.rb
 - lib/agoo/version.rb
 - lib/rack/handler/agoo.rb
+- misc/flymd.md
+- misc/glue-diagram.svg
+- misc/glue.md
+- misc/optimize.md
+- misc/push.md
+- misc/rails.md
+- misc/song.md
 - test/base_handler_test.rb
 - test/bind_test.rb
 - test/domain_test.rb
@@ -164,7 +178,9 @@ homepage: https://github.com/ohler55/agoo
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/ohler55/agoo/issues
   changelog_uri: https://github.com/ohler55/agoo/CHANGELOG.md
+  documentation_uri: http://www.ohler.com/agoo/index.html
   source_code_uri: https://github.com/ohler55/agoo
   homepage: https://github.com/ohler55/agoo
 post_install_message:
@@ -193,7 +209,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - Linux or macOS
-rubygems_version: 3.4.10
+rubygems_version: 3.4.1
 signing_key:
 specification_version: 4
 summary: An HTTP server