tla-sbuilder 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c7c59bc7c8ccd8cc4c991d487f793208c1234bab
-  data.tar.gz: 564a18b8c901b8714dfb32c7c70d0a78b5a8f7ac
+  metadata.gz: b4731a435e4630bf464dd4d183d3a40df97e1e38
+  data.tar.gz: 8c4e8a335e829e7df768069dfb3b276e199f2913
 SHA512:
-  metadata.gz: 208032b65aff58ad9a32ae7f4197da74b24979defcf30886bcbcd32974571b34da94c80f027dddea217bfea2a7d71c254aa8b93b06f7f94d80433960818c90dd
-  data.tar.gz: 667f6dd2647f7e60cb1bfde14f28d55703c57b1b16f3dc33e2fbf1ca7c61d320feb9d51ea89856d544ba48da6f295f2e35b21547e20d9beed63c11ff9985007a
+  metadata.gz: 7135b56dc4e078cc4f950402b3245e5bf239ea5718da7fd86c20f48fbdec39d00e06cc93f34fc2a8dfd90e727a5e6e6b9ddb41f212c510c9f604f28cc9a6954c
+  data.tar.gz: ad58191062c7e450f97f2e8f51c6deddf1eed8a39378c1775a44770be3dae2708b185340ce7022e194d04edadaac308a4b289999383568381f9ed3895bcfd89a

data/README.md

@@ -1,8 +1,7 @@
 <link href="../site.css" rel="stylesheet"></link>
-[Up](../index.php) [Readme](README.html) [Releases](RELEASES.html) [Todo](TODO.html)
+[Readme](README.md) [Releases](RELEASES.md)
 
-
-# Sbuilder - A Specification Builder for TLA+ Tools - $Release:0.1.0$
+# Sbuilder - A Specification Builder for TLA+ Tools - $Release:0.2.1$
 
 A tool to generate runnable specification models in
 [TLA+ language](http://research.microsoft.com/en-us/um/people/lamport/tla/book.html)
@@ -12,7 +11,24 @@ verified using
 and parts of it can be presented as
 [implementation blueprints](#BLUEPRINT) to developers.
 
-See [live documentation](features.html) for more details.
+See
+[live documentation](http://jarjuk.github.io/tla-sbuilder/0.1.1.pre/features.html)
+for more details on configuring Sbuilder, and on features implemented
+by Sbuilder
+
+Blog posts giving background information on Sbuilder:
+
+* [Read an article "How Amazon uses formal methods"](https://jarjuk.wordpress.com/2016/03/03/sbuilder-1-problem):
+  summarizes experiences Amazon has gained, when using TLA+ tools,
+  what kind of benefits we should expect, when using formal methods to
+  model business IT
+
+* [Sbuilder introduction](https://jarjuk.wordpress.com/2016/03/03/sbuilder-2-intro/):
+  mostly the same information as in this README
+
+* [Using Sbuilder to Model Business IT Systems](https://jarjuk.wordpress.com/2016/03/03/sbuilder-3-case/):
+  a very loooong post demonstrating, how business IT system modeling
+  can be done using Sbuilder
 
 ## <a id="TARGET-SYSTEM">Target Systems</a>
 
@@ -36,11 +52,13 @@ architecture identifies
 Sbuilder combines three main elements to create runnable TLA+
 specification code:
 
-1. **Interface specification**: Sbuilder accepts
+1. **Interface specification**: Natively Sbuilder accepts
   [RESTfull](https://en.wikipedia.org/wiki/Representational_state_transfer)
   interface api specification expressed in
   [Swagger](http://swagger.io/)
-  [v2.0](http://swagger.io/specification/) format.
+  [v2.0](http://swagger.io/specification/) format. Plugin system
+  allows importing API confiugration also from external systems,
+  e.g. from [salesforce](https://github.com/jarjuk/tla-sbuilder-salesforce)
   
 2. **Specification extension**: Sbuilder tangles manually crafted code
    snippets from Sbuilder *code repository* with the code generated
@@ -48,12 +66,12 @@ specification code:
    TLA+ language to model behavior and correctness criteria of the
    target system.
   
-3. **Setups**: To complete runnable code, Sbuilder uses setups. A
-   setup is a sequence of interface operations, and their input
-   parameters.  In addition, a setup may define domain cardinalities,
-   or domain values.  The tools allows defining multiple setups, each
-   setup resulting to a complete, runnable TLA+ code, allowing system
-   model to be run in various environment context
+3. **Setups**: To complete runnable code Sbuilder uses setups. A setup
+   is a sequence of interface operations, and their input parameters.
+   In addition, a setup may define domain cardinalities, or domain
+   values.  The tools allows defining multiple setups, each setup
+   resulting to a complete, runnable TLA+ code, allowing system model
+   to be run in various environment context
 
 Sbuilder uses following categories to organize *specification
 snippets* in its **code repository**:
@@ -82,16 +100,15 @@ snippets* in its **code repository**:
 * **possibility**: optional operator definitions to increase
   confidence in correctness invariants
 
-* **assumption**: operator definitions, and ASSUME directive in TLA+
-  language specifying properties, which must be not violated in the
-  specification code
+* **assumption**: operator definitions, in TLA+ language specifying
+  properties on specification model constants, which must be not
+  violated.
 
-In order to support IT system application development, as depicted in
-section [modeling pipeline](#MODELING-PIPELINE) below, Sbuilder
-can generate <a id="BLUEPRINT">**implementation
-blueprints**</a>. *Implementation blueprints* are html-pages including
-code snippets from Sbuilder *code repository*, or code generated
-based on *interface specifications*.
+Sbuilder can generate <a id="BLUEPRINT">**implementation
+blueprints**</a> as depicted in section
+[modeling pipeline](#MODELING-PIPELINE) below. *Implementation
+blueprints* are html-pages including code snippets from Sbuilder *code
+repository*, or code generated based on *interface specifications*.
 
 
 ## <a id="MODELING-PIPELINE">Modeling Pipeline</a>
@@ -105,7 +122,7 @@ the system being built - and thereby to justify the extra effort
 needed in modeling.
 
 
-![process](pics/process.svg)
+![process](pics/process.jpg)
 
 We assume that services are currently implemented based on informal
 service specification documents written in English. We also assume
@@ -264,7 +281,7 @@ and observing **Error: Evaluating invariant** `possible_tag_with_invalid_address
 
 ### Create Own Model
 
-See [live documentation](features.html) for more details.
+See [live documentation](http://jarjuk.github.io/tla-sbuilder/0.1.1.pre/features.html) for more details.
 
 Create default directories used by `sbuilder` in current working directory
 
@@ -291,6 +308,20 @@ To run the model checking for setup `default` using TLA+tools jar in
 	(cd gen/default/tla; java -cp  $CP tlc2.TLC setup)
 
 
+Create TLA snippets in directory `src`, and include template snippets
+to generated code using
+[mustache syntax](https://mustache.github.io/mustache.5.html).
+
+For example, put the following code to 
+
+	at_least_two_tags == Cardinality( v_tags ) > 1
+
+file `src/operator_at_least_two_tags.tla`, and include it to
+specification code by adding following line into `src/operator`
+
+	{{>operator_at_least_two_tags.tla}}
+
+
 ## Manage State Space Explosion, and Allow Scaling
 
 [State space explosion](https://www.google.fi/search?q=state+space+explosion)
@@ -298,21 +329,24 @@ is inherent problem in
 [model checking](https://en.wikipedia.org/wiki/Model_checking), the
 theory behind TLA+ tool.
 
-Sbuilder tries to avoid problems due to state space explosion by 
+Sbuilder tries to avoid problems due to state space explosion by
+controlling, how environment invokes interface operations, and in
+effect, by throttling number of states generated during model
+checking.
 
-* allowing controlling, how environment invokes interface operations,
-  and in effect, throttling number of states generated during model
-  checking.
+To avoid enumering to0 large sets Sbuilder allows
 
-* allowing to fix input parameter bindings in an interface
-  operation. In cases, where domain sizes are not a problem, SBuilder
-  can allow TLA+ tool to explore all possible, or partial, input
-  parameter combinations during model checking.
+* fixing input parameter bindings in an interface operation. In cases,
+  where domain sizes are not a problem, SBuilder allows TLA+ tool to
+  use non-deterministic choice for input parameter values.
 
+* using reduced domain ranges, when checking assumptions on resolved
+  domains.
 
 In TLA+tools, number of states/sec decreases as specification code
-volume increases (see a [benchmark](BENCHMARK.html) results for more
-details).
+volume increases (see a
+[benchmark](https://rawgit.com/jarjuk/tla-sbuilder/master/BENCHMARK.html)
+results for more details).
 
 SBuilder tries to avoid problems due to increase in specification code
 by offering run time option `--filter-src`, which parses TLA+ snippets
@@ -322,6 +356,55 @@ option `--filter-list` to continue after parser error, and to
 configure manually modules call flow analyzer would otherwise omit
 from the specification code.
 
+## Extending Sbuilder
+
+Sbuilder defines an extension point to add API loader plugins. An API
+loader is a Ruby class
+
+* using [Sbuilder::ApiLoader](lib/sbuilder/facade/api_loader.rb)
+  facade to integrate with Sbuilder
+
+* satisfying [`api_loader_facade` contract](lib/sbuilder/spec/api_loader_facade.rb)
+
+* used as demonstated in [cucumber tests](features/100-plugin-extension/010-api-loader-plugin.feature)
+
+For a plugin implementation example, see an Swagger API loader in
+Sbuilder:
+
+* [implementation](lib/sbuilder/param_set_loader_swagger.rb)
+
+* [rpsec test](spec/sbuilder/param_set_loader_swagger_spec.rb)
+
+For example, to activate Sbuilder API loader plugin
+`Sbuilder::Interfaces::Salesforce::SalesforceLoader` implemented in
+`tla-sbuilder-salesforce` Gem using configuration hash shown below,
+add the following YAML snippet to `sbuilder.yaml` configuration file
+sub-section `extend.loaders`:
+
+    extend:
+          loaders:
+              - gem: tla-sbuilder-salesforce
+                className: Sbuilder::Interfaces::Salesforce::SalesforceLoader
+                configuration:
+                      client_id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxdaYTBJBssnuS0bvkraFcSSlC9EQZngf97yspdbh8iV_EV
+                      client_secret: xxxxxxxxxx476009913
+                      username: xxxxxxxev@gmail.com
+                      password: 'xxxxxxxx'
+                      security_token:  'xxxxxxxxxxVnEZjYP9cUZix9'
+
+API instances are configured using entries referring plugin
+`className` in `sbuilder.yaml` `interfaces` array.  For example, the
+entry for an Salesforce API instance entry.
+
+     interfaces:
+        -  className: Sbuilder::Interfaces::Salesforce::SalesforceLoader
+           file: salesforce-api.yaml
+		   cache: sf
+           
+In the example, `file` -property points to a plugin configuration
+file, and `cache` property gives name prefix for files, which the
+plugin may use to cache API content to speed up generation phase.
+
 
 ## License 
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.1

data/lib/cli/cli-customer.rb

@@ -13,24 +13,34 @@ module Sbuilder
 
     
     FILE_EXTENSIONS_CUSTOMER_COMMON="extend_customer_doms.yaml"
+    FILE_EXTENSIONS_CUSTOMER_IF="extend_customer_if.yaml"    
     FILE_EXTENSIONS_CUSTOMER_RUN1="extend_customer_run1.yaml"
     FILE_EXTENSIONS_CUSTOMER_RUN2="extend_customer_run2.yaml"                
     
-    SBUILDER_YAML_CUSTOMER= <<-EOS
+    SBUILDER_YAML_CUSTOMER= <<-EOS.unindent
+
+    # ------------------------------------------------------------------
+    #{Sbuilder::CliText::SBUILDER_PREFERENCES}
+    preferences:
+          debug-output: true
+
+    # ------------------------------------------------------------------
+    #{Sbuilder::CliText::SBUILDER_EXTENSION}
+
 
     # ------------------------------------------------------------------
     #{Sbuilder::CliText::SBUILBER_INTERFACES}
 
     interfaces:
-        -  type: swagger
+        -  
+           className: Sbuilder::ParamSetLoaderSwagger
            file: #{FILE_INTERFACE_CUSTOMER}
 
 
     # ------------------------------------------------------------------
     #{Sbuilder::CliText::SBUILDER_RESOLVERS}
     resolvers:
-        -  type: resolver_yaml
-           file: #{FILE_RESOLVER_CUSTOMER}
+         - file: #{FILE_RESOLVER_CUSTOMER}
 
     # ------------------------------------------------------------------
     #{Sbuilder::CliText::SBUILER_SETUPS}
@@ -39,34 +49,32 @@ module Sbuilder
 
         - setupDirectory: customer1
           extensions:
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_CUSTOMER_COMMON}
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_CUSTOMER_RUN1}
+            -  url: cnf/#{FILE_EXTENSIONS_CUSTOMER_COMMON}
+            -  url: cnf/#{FILE_EXTENSIONS_CUSTOMER_IF}
+            -  url: cnf/#{FILE_EXTENSIONS_CUSTOMER_RUN1}
 
         - setupDirectory: customer2
           extensions:
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_CUSTOMER_COMMON}
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_CUSTOMER_RUN2}
+            -  url: cnf/#{FILE_EXTENSIONS_CUSTOMER_COMMON}
+            -  url: cnf/#{FILE_EXTENSIONS_CUSTOMER_IF}
+            -  url: cnf/#{FILE_EXTENSIONS_CUSTOMER_RUN2}
 
     # ------------------------------------------------------------------
-    #{Sbuilder::CliText::SBUILDER_PREFERENCES}
-    preferences:
-          debug-output: true
 
-    # ------------------------------------------------------------------
     #{Sbuilder::CliText::SBUILDER_GENERATE}
 
 
-    EOS
+    # ------------------------------------------------------------------
 
-    
+    #{Sbuilder::CliText::SBUILDER_INVARIANTS}
+    invariants:
+        # - Invariant1: Add TLA operator definition Invariant1 and uncomment this line
 
 
+    EOS
 
-    EXTENSIONS_CUSTOMER_COMMON = <<-EOS
+    
+    EXTENSIONS_CUSTOMER_COMMON = <<-EOS.unindent
     #{Sbuilder::CliText::EXTENSION_HEADER_DOM}
     #
     #
@@ -87,7 +95,17 @@ module Sbuilder
 
     EOS
 
-    EXTENSIONS_CUSTOMER_RUN1 = <<-EOS
+    EXTENSIONS_CUSTOMER_IF = <<-EOS.unindent
+    #{Sbuilder::CliText::EXTENSION_HEADER_IF}
+    #
+    # Exampl uses dummy process, which should be replaced with real implementation
+    - interface-extension:
+          - matcher: /customers(post)
+            implementation: dummy
+    EOS
+    
+
+    EXTENSIONS_CUSTOMER_RUN1 = <<-EOS.unindent
     #{Sbuilder::CliText::EXTENSION_HEADER_SETUP}
     #
     # Extend domain resolved in #{FILE_RESOLVER_CUSTOMER} 
@@ -175,7 +193,7 @@ module Sbuilder
 
     EOS
     
-    EXTENSIONS_CUSTOMER_RUN2 = <<-EOS
+    EXTENSIONS_CUSTOMER_RUN2 = <<-EOS.unindent
     #{Sbuilder::CliText::EXTENSION_HEADER_SETUP}
     #
     #
@@ -205,7 +223,7 @@ module Sbuilder
     
     
 
-    RESOLVER_CUSTOMER = <<-EOS
+    RESOLVER_CUSTOMER = <<-EOS.unindent
     #{Sbuilder::CliText::RESOLVER_HEADER}
     #
     # Example mapper for customer interface
@@ -281,7 +299,7 @@ module Sbuilder
     EOS
 
     
-    INTERFACE_CUSTOMER_SWAGGER = <<-EOS
+    INTERFACE_CUSTOMER_SWAGGER = <<-EOS.unindent
     # Example YAML configuration file
     # 
     swagger: "2.0"

data/lib/cli/cli-example.rb

@@ -21,7 +21,6 @@ module Sbuilder
       CliPet.write_files( dir, self )
       # sbuilder - example sources
       write_example_dir
-      
     end
 
     desc :customer, "Create 'Customer' TLA+ model <cnf_dir> -directory"
@@ -35,6 +34,7 @@ module Sbuilder
       write_example( dir, Sbuilder::CliCustomer::FILE_RESOLVER_CUSTOMER, Sbuilder::CliCustomer::RESOLVER_CUSTOMER )
       write_example( dir, Sbuilder::CliCustomer::FILE_INTERFACE_CUSTOMER, Sbuilder::CliCustomer::INTERFACE_CUSTOMER_SWAGGER )
       write_example( dir, Sbuilder::CliCustomer::FILE_EXTENSIONS_CUSTOMER_COMMON, Sbuilder::CliCustomer::EXTENSIONS_CUSTOMER_COMMON )
+      write_example( dir, Sbuilder::CliCustomer::FILE_EXTENSIONS_CUSTOMER_IF, Sbuilder::CliCustomer::EXTENSIONS_CUSTOMER_IF )      
       write_example( dir, Sbuilder::CliCustomer::FILE_EXTENSIONS_CUSTOMER_RUN1, Sbuilder::CliCustomer::EXTENSIONS_CUSTOMER_RUN1 )
       write_example( dir, Sbuilder::CliCustomer::FILE_EXTENSIONS_CUSTOMER_RUN2, Sbuilder::CliCustomer::EXTENSIONS_CUSTOMER_RUN2 )
       

data/lib/cli/cli-pet.rb

@@ -28,14 +28,14 @@ module Sbuilder
 
     interfaces:
 
-        -  type: swagger
+        -  className: Sbuilder::ParamSetLoaderSwagger
            url: #{PETSTORE_URL}
            cache: petstore.yaml
 
-        -  type: swagger
+        -  className: Sbuilder::ParamSetLoaderSwagger
            file: #{FILE_INTERFACE_TAGS}
 
-        -  type: swagger
+        -  className: Sbuilder::ParamSetLoaderSwagger
            infrastructureServices: true
            file: #{FILE_INFRASTRUCTURE_PETSTORE}
 
@@ -43,8 +43,7 @@ module Sbuilder
     # ------------------------------------------------------------------
     #{Sbuilder::CliText::SBUILDER_RESOLVERS}
     resolvers:
-        -  type: resolver_yaml
-           url: cnf/#{FILE_RESOLVER_PETSTORE}
+        -  url: cnf/#{FILE_RESOLVER_PETSTORE}
         # un-comment to use default resolver.
         # normally not used
         # -  type: resolver_yaml
@@ -54,50 +53,46 @@ module Sbuilder
     #{Sbuilder::CliText::SBUILER_SETUPS}
     setups:
         - setupDirectory: default
-
+          desc: Validate assumptions
+          assumptions:
+             - Assume_Address_Domains
+             - Assume_Id_Domains
+             - Assume_Tag_Domains		
+             - Assume_Owner_Domains
+             - Assume_Pet_Domains
         - setupDirectory: pet1
           extensions:
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_PETSTORE_COMMON}
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_PETSTORE_RUN1}
+            -  url: cnf/#{FILE_EXTENSIONS_PETSTORE_COMMON}
+            -  url: cnf/#{FILE_EXTENSIONS_PETSTORE_RUN1}
           possibilities: 
             - tag_with_invalid_address
             - at_least_two_tags
 
         - setupDirectory: pet2
           extensions:
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_PETSTORE_COMMON}
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_PETSTORE_RUN2}
+            -  url: cnf/#{FILE_EXTENSIONS_PETSTORE_COMMON}
+            -  url: cnf/#{FILE_EXTENSIONS_PETSTORE_RUN2}
 
         - setupDirectory: pet3
           extensions:
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_PETSTORE_COMMON}
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_PETSTORE_RUN3}
+            -  url: cnf/#{FILE_EXTENSIONS_PETSTORE_COMMON}
+            -  url: cnf/#{FILE_EXTENSIONS_PETSTORE_RUN3}
           possibilities: 
             - tag_with_invalid_address
             - at_least_two_tags
 
         - setupDirectory: pet-svg
           extensions:
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_PETSTORE_COMMON}
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_PETSTORE_RUN_SVG}
+            -  url: cnf/#{FILE_EXTENSIONS_PETSTORE_COMMON}
+            -  url: cnf/#{FILE_EXTENSIONS_PETSTORE_RUN_SVG}
 
         - setupDirectory: error-invalidate-name
           desc: Owner name is invalidate on a tag referenced
           preferences:
                error-invalidate-name: true
           extensions:
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_PETSTORE_COMMON}
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_PETSTORE_RUN3}
+            -  url: cnf/#{FILE_EXTENSIONS_PETSTORE_COMMON}
+            -  url: cnf/#{FILE_EXTENSIONS_PETSTORE_RUN3}
 
 
         - setupDirectory: error-duplicate-tag
@@ -105,10 +100,8 @@ module Sbuilder
           preferences:
                error-duplicate-tag: true
           extensions:
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_PETSTORE_COMMON}
-            -  type: default-yaml
-               url: cnf/#{FILE_EXTENSIONS_PETSTORE_RUN3}
+            -  url: cnf/#{FILE_EXTENSIONS_PETSTORE_COMMON}
+            -  url: cnf/#{FILE_EXTENSIONS_PETSTORE_RUN3}
 
 
     # ------------------------------------------------------------------
@@ -294,6 +287,16 @@ module Sbuilder
            #        include: definition_types.mustache
 
 
+    #{Sbuilder::CliText::SBUILDER_INVARIANTS}
+    invariants:
+          - ValidatePets: All pet entries are valid
+          - UniquePet: Pet id is unique
+          - UniqueTag: Tag id is unique
+          - ValidReferecendTag: For all pets there exists a unique, valid tag entry.
+          - CoherentOwnerAddress: Address on all tags with the same ower are equal
+          - Pets_TypeInvariant: Type invariant Pet
+          - Tags_TypeInvariant: Type invariant Tag
+
     EOS
 
     EXTENSIONS_PETSTORE_COMMON = <<-EOS