picatrix 0.5.0 → 0.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 28283e340d828d5a22f3152ccd81c502b863eccf
-  data.tar.gz: d5c7a1a4234333f7002f3a6016c325a1fcd6f636
+  metadata.gz: cfdec538080a26d183c8338917e4906c48f12df3
+  data.tar.gz: 9795226f4ca351fda88a3caa0a9bd668e941f766
 SHA512:
-  metadata.gz: c71a9ae39ddf75673c92affe67f2a93e5e61e81aef091596de7a037109ee301cf731439c67b4659cc8393d6de8b61f6910ddde9ba3639f11fbdfe4c36849e9c4
-  data.tar.gz: 4f113d91d4e052728a87cdc347a902c732b2e3df02a33b150d2524fcb183b6a5caa1d6bd2e8d75afd97625a7a45d4594239389fa99822c8e80872195cf686b1d
+  metadata.gz: d6af26dcf377adbd88a4e7bbf057b0c367a1c4b4b90503f292a1c1f08295562fc9a6f48b3356d4ec10d4b6ba65e0cd2bd74fca7212f2725e60e3488c6df90552
+  data.tar.gz: 6a9cf7fd9b51d021800a8c726f96cc31c4d952b2741e1d01d76abaa9c30e20730a6574c3f305c5dfe58db644b20d64d0d60933ed83685a0828a4129bb641e656

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    picatrix (0.2.0)
+    picatrix (0.5.0)
       activesupport
       faker
       grape

data/README.md

@@ -9,27 +9,21 @@
 
 An opinionated hypermedia API generator. :grin:
 
-## Requires:
+## Requires
 
 - valid `.dot` file with [additional style guidelines](#dot-file-styles)
 - Protobuf [definitions of inputs/outputs](#protobuf-definitions-of-representations) for all state transitions, by node
 
 
-## Outputs:
+## Outputs
 
 - basic Sinatra app and mock objects fitting your schema
-  - protobuf generated representation objects (you dont edit these)
-  - fixture interface to map to your persistance layer, is generated with fake data generators (you do edit these)
-- `application/vnd.mason+json`
-  - controls
+  - intended to be a scaffold for your client to immediately test against, and maybe for you to build from or to (to as in match its interface in contract)
+  - `application/vnd.mason+json` hypermedia affordances
+  - CRUD + Filter actions are defined for you by default
+  - `$select` and `$expand` URL conventions apply
 - state diagram image ([see below](https://github.com/mooreniemi/picatrix#sample-image-output))
 
-## About
-
-Directed graphs get complicated, but can be divided into simpler subgraphs. Picatrix is currently useful for only a single workflow (and barely that right now, as we're way before a real release). Integrated workflows will involve generating several route sets that will be required into a single Sinatra app. Some workflows may even be representable as DAGs/trees.
-
-The ideal way to use Picatrix is to do an exercise in designing your API "outside in" where all inputs/outputs are defined, and a state diagram is drawn. This diagram can be translated to a dot file, and the inputs/outputs can be translated into hypermedia assets.
-
 ## Installation
 
 Install system dependencies (Mac OS sample):
@@ -54,6 +48,8 @@ Or install it yourself as:
 
 ## getting ready
 
+  - easiest thing to do is use the rake task provided to make yourself a copy of the sample `dot` file which you can edit
+
 ### .dot file styles
 
   - edge style defaults to `arrowhead=odiamond` to signify default requests are `GET`
@@ -71,12 +67,15 @@ Or install it yourself as:
     - from the perspective of the client at any request, what does it need to make the request and have the server fufill its contract?
     - from the perspective of the server, what might the client want in response for it to make any interesting subsequent requests from this node in the workflow?
     - inputs will map onto controls, and outputs will map on to representations (dereferenced content)
-## Usage
 
-In its final state, the intent is to use it as a CLI:
+## Usage
 
 ```bash
-$ bin/picapica dg_api.dot app_name
+$ bin/picapica prep dg_api.dot app_name
+=> generated/app_name.proto
+# at this point you flesh out your schema in your proto file
+$ vi generated/app_name.proto
+$ bin/picapica g dg_api.dot app_name
 => generated/app_name.rb
 ```
 
@@ -89,29 +88,10 @@ $ bin/picapica dg_api.dot app_name
 
 ### how to interpret the graph
 
-Nodes and edges translate roughly into application and/or resource states, and state transitions.
-
-Labels on edges are link relations. Confusingly the actual _URL_ of the state transition (moving to the next state) is still the target node (essentially, think of the state transition name as the same as the name of the ideal output) _and_ its link relation to its source. So, `A (make_B_do_x)-> B` is `B/make_B_do_x`. This is still (obviously) sketchy.
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-### TODO
-
-process goes: .dot file + `prep` (1)-> proto file from nodes + user input into .proto + `proto` (2)-> ruby representation classes + user input to fixturize (3)-> `g` (4)-> `rackup lib/picatrix/generated/app.rb`
-
-1. outside in design process produced a diagram, which is written into a .dot file
-2. all nodes are representations of resources, and thus get proto objects generated for them, here is where the inputs/outputs are formed into a schema
-3. representation nodes now have ruby classes that reflect the information that will be sent back and forth in messages so we generate the app
-4. boot up the app
-
-## Contributing
-
-Bug reports and pull requests are welcome on [GitHub](https://github.com/mooreniemi/picatrix). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Nodes and edges translate roughly into application and/or resource states, and state transitions. Labels on edges are link relations.
 
+## see also
+[more notes](more-notes.md)
 
 ## License
 

data/Rakefile

@@ -5,3 +5,38 @@ load 'protobuf/tasks/compile.rake'
 RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec
+
+namespace :test do
+  desc "flesh out the proto file so you can generate from it"
+  task :setup do
+    puts "copying app.proto from spec/support/definitions/"
+    `cp spec/support/definitions/app.proto generated/app.proto`
+  end
+
+  desc "regen ruby from protobuf"
+  task :regen do
+    puts "regenerating ruby classes from mock definitions"
+    `protoc -I ./lib/picatrix/support -I ./generated --ruby_out ./generated/support generated/app.proto`
+  end
+
+  desc "serve example app (you may need to run test:setup first)"
+  task :serve do
+    `rackup generated/app.rb`
+  end
+
+  desc "generate new image of example graph"
+  task :png do
+    `dot -Tpng spec/support/dg_api.dot -o spec/support/dg_api.dot.png`
+  end
+end
+
+namespace :app do
+  desc "generate .dot file to work with"
+  task :dot, [:name] do |t, args|
+    `cp spec/support/dg_api.dot generated/#{args[:name]}.dot`
+  end
+  desc "serve your app by name"
+  task :serve, [:name] do |t, args|
+    `rackup generated/#{args[:name]}.rb`
+  end
+end

data/bin/console

@@ -1,13 +1,17 @@
 #!/usr/bin/env ruby
 
 require "bundler/setup"
+
+$LOAD_PATH.unshift File.expand_path('../../generated', __FILE__)
 require "picatrix"
 
-# generate ruby classes
-`protoc -I ./definitions --ruby_out ./lib/picatrix/generated definitions/*.proto`
+puts "regen mason"
+`protoc --ruby_out . lib/picatrix/support/picatrix.mason.proto`
+
+puts "regen test app"
+`protoc -I ./lib/picatrix/support -I ./generated --ruby_out ./generated generated/app.proto`
 
-require './lib/picatrix/generated/mason.pb.rb'
-require './lib/picatrix/generated/app.pb.rb'
+require './generated/app.pb.rb'
 
 require "pry"
 Pry.start

data/bin/post-receive.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+echo "ಠ╭╮ಠ"
+git grep -i --color --break -n "TODO"

data/bin/setup

@@ -2,6 +2,12 @@
 set -euo pipefail
 IFS=$'\n\t'
 
+echo "installing graphviz"
+brew install graphviz
+echo "installing protobuf"
+brew install protobuf
+echo "installing bundler"
+gem install bundler
+
 bundle install
 
-# Do any other automated setup that you need to do here

data/generated/zoo.dot

@@ -0,0 +1,37 @@
+digraph d {
+  // means default method is GET
+  sep="+25,25";
+  overlap=scalexy;
+  nodesep=0.6;
+  splines=true;
+  graph [overlap = false];
+  edge [
+    arrowhead=odiamond
+    // this is just to make it more readable, set it to anything you want
+    fontcolor=blue
+  ]
+
+  // node definitions
+  // interpret shape=point as root
+  root [xlabel="inbound request" shape=point]
+  // shape=folder means collection
+  animals [label="View animals" shape=folder]
+  // shape=rectangle means item
+  animal [label="View animal" shape=rectangle]
+
+  // edge definitions
+  // source -> { target } [label="link relation name"]
+  root -> { animals } [label="newest"]
+  // style=dotted means inline representation
+  animals -> { animal } [label=":item_id"]
+  animals -> { animals } [label="filter"]
+  // style=bold && arrowhead=normal means POST
+  animals -> { animal } [label="create" style=bold arrowhead=normal]
+  // non-CRUD + Filter link relations will also be inflated
+  // animals -> { animals } [label="custom_relation" style=bold arrowhead=normal]
+  animal -> { animals } [label="newest"]
+  // color=red && fontcolor=red means DELETE
+  animals -> { animals } [label="newest" color=red fontcolor=red]
+  // arrowhead=normal means PATCH or PUT (if patch not supported)
+  animal -> { animal } [label="edit" arrowhead=normal]
+}

data/{lib/picatrix/generated/view_submissions.rb → generated/zoo/resources/animals.rb}

@@ -6,24 +6,18 @@ require 'faker'
 # technically, this is just an interface to it
 # so long as your persistance layer is able to implement
 # the methods in this fixture, the app will generate
-class ViewSubmissionsResource
+class AnimalsResource
   # method used to return single item from a collection
   # creates an instance on the fly
   # both the find and collection methods use this
   def self.create(item_id)
-    ViewSubmission.new(
+    Animal.new(
       {
         # any "bare" Proto type will be given an associated Faker
         
         :id => id = Faker::Number.number(6),
         
-        :category => Faker::Lorem.word,
-        
-        :photo => Faker::Lorem.word,
-        
-        :controls => ViewSubmission::Controls.new(minimal_controls_for(item_id)),
-        
-        :attachments => [ViewSubmission::Attachment.new(params = {})],
+        :controls => Animal::Controls.new(minimal_controls_for(item_id)),
         
       }
     )
@@ -36,14 +30,17 @@ class ViewSubmissionsResource
     rand(10).times {
       collection << self.find(rand(1000))
     }
-    ViewSubmissions.new(collection: collection)
+    Animals.new(collection: collection)
   end
-
+  def self.as_hashes
+    self.all.collection.map(&:to_hash)
+  end
+  # this makes no sense on this class
   def self.minimal_controls_for(item_id)
     host = "http://localhost:9292"
     {
-      self: Mason::Self.new(href: "#{host}/view_submission/#{item_id}"),
-      up: Mason::Up.new(href: "#{host}/view_submissions")
+      self: ::Picatrix::Mason::Self.new(href: "#{host}/animals/#{item_id}"),
+      up: ::Picatrix::Mason::Up.new(href: "#{host}/animals")
     }
   end
 end

data/generated/zoo/support/mason.rb

@@ -0,0 +1,114 @@
+module Picatrix
+  module Mason
+    def mason_up(type)
+      if type.to_s.pluralize == type
+        proc do |path, params|
+          {
+            up: Mason::Up.new(
+              {
+                href: "http://localhost:9292/#{}"
+              }
+            ).to_hash
+          }
+        end
+      else
+        proc do |path, params|
+          {
+            up: Mason::Up.new(
+              {
+                href: "http://localhost:9292/#{path.pluralize}"
+              }
+            ).to_hash
+          }
+        end
+      end
+    end
+    def mason_self(item)
+      proc do |path, params|
+        if params[:item_id]
+          {
+            self: Mason::Self.new(
+              {
+                href: "http://localhost:9292/#{path}/#{params[:item_id]}"
+              }
+            ).to_hash
+          }
+        else
+          {
+            self: Mason::Self.new(
+              {
+                href: "http://localhost:9292/#{path}"
+              }
+            ).to_hash
+          }
+        end
+      end
+    end
+    def edit(item)
+      proc do |path, params|
+        {
+          "z:edit": Mason::Edit.new(
+            {
+              href: "http://localhost:9292/#{path}/#{params[:item_id]}",
+              method: Mason::HTTPVerb::PATCH
+            }
+          ).to_hash
+        }
+      end
+    end
+    def remove(item)
+      proc do |path, params|
+        {
+          "z:remove": Mason::Remove.new(
+            {
+              href: "http://localhost:9292/#{path}/#{params[:item_id]}",
+              method: Mason::HTTPVerb::DELETE
+            }
+          ).to_hash
+        }
+      end
+    end
+    def create(collection)
+      proc do |path, params|
+        collection_name = collection.to_s.camelize
+        {
+          "z:create": Mason::Create.new(
+            {
+              href: "http://localhost:9292/#{path}",
+              method: Mason::HTTPVerb::POST,
+              title: "Create a new #{collection_name}",
+              create_template: "#{collection_name}CreateTemplate".constantize.new({})
+            }
+          )
+        }
+      end
+    end
+    def filter(collection)
+      proc do |path, params|
+        if params[:newest]
+          {
+            "z:filter": Mason::Filter.new(
+              {
+                href: "http://localhost:9292/#{path}?filter=newest",
+                isHrefTemplate: true,
+                method: Mason::HTTPVerb::GET,
+                title: "Show the newest additions to #{collection}"
+              }
+            ).to_hash
+          }
+        else
+          {
+            "z:filter": Mason::Filter.new(
+              {
+                href: "http://localhost:9292/#{path}?$select&{field1}={value1}&{field2}={value2}",
+                isHrefTemplate: true,
+                method: Mason::HTTPVerb::GET,
+                title: "Filter using $select on schema fields"
+              }
+            ).to_hash
+          }
+        end
+      end
+    end
+  end
+end

data/generated/zoo/support/namespaces.json

@@ -0,0 +1,7 @@
+{
+  "@namespaces": {
+      "z": {
+            "name": "http://localhost:9292/rels#"
+          }
+    }
+}

data/generated/zoo/support/picatrix.mason.pb.rb

@@ -0,0 +1,95 @@
+# encoding: utf-8
+
+##
+# This file is auto-generated. DO NOT EDIT!
+#
+require 'protobuf/message'
+
+module Picatrix
+  module Mason
+
+    ##
+    # Enum Classes
+    #
+    class HTTPVerb < ::Protobuf::Enum
+      define :GET, 1
+      define :PUT, 2
+      define :PATCH, 3
+      define :DELETE, 4
+      define :POST, 5
+    end
+
+
+    ##
+    # Message Classes
+    #
+    class Self < ::Protobuf::Message; end
+    class Up < ::Protobuf::Message; end
+    class Filter < ::Protobuf::Message; end
+    class Create < ::Protobuf::Message; end
+    class Edit < ::Protobuf::Message; end
+    class Remove < ::Protobuf::Message; end
+    class Controls < ::Protobuf::Message; end
+
+
+    ##
+    # Message Fields
+    #
+    class Self
+      optional :string, :href, 1
+      optional :string, :title, 2
+    end
+
+    class Up
+      optional :string, :href, 1
+      optional :string, :title, 2
+    end
+
+    class Filter
+      optional :string, :href, 1
+      required ::Picatrix::Mason::HTTPVerb, :method, 2, :default => ::Picatrix::Mason::HTTPVerb::GET
+      required :bool, :isHrefTemplate, 3, :default => true
+      optional :string, :title, 4
+      # Extension Fields
+      extensions 10...20
+    end
+
+    class Create
+      optional :string, :href, 1
+      required ::Picatrix::Mason::HTTPVerb, :method, 2, :default => ::Picatrix::Mason::HTTPVerb::POST
+      optional :string, :title, 3
+      optional :string, :encoding, 4
+      # Extension Fields
+      extensions 10...20
+    end
+
+    class Edit
+      optional :string, :href, 1
+      required ::Picatrix::Mason::HTTPVerb, :method, 2, :default => ::Picatrix::Mason::HTTPVerb::PATCH
+      optional :string, :title, 3
+      optional :string, :encoding, 4
+      # Extension Fields
+      extensions 10...20
+    end
+
+    class Remove
+      optional :string, :href, 1
+      required ::Picatrix::Mason::HTTPVerb, :method, 2, :default => ::Picatrix::Mason::HTTPVerb::DELETE
+      optional :string, :title, 3
+      # Extension Fields
+      extensions 10...20
+    end
+
+    class Controls
+      optional ::Picatrix::Mason::Self, :self, 2
+      optional ::Picatrix::Mason::Up, :up, 3
+      optional ::Picatrix::Mason::Edit, :edit, 4
+      optional ::Picatrix::Mason::Remove, :remove, 5
+      optional ::Picatrix::Mason::Create, :create, 6
+      optional ::Picatrix::Mason::Filter, :filter, 7
+    end
+
+  end
+
+end
+