From a7424d4895ad7abe4933b425e718a6bdf1a0c22f Mon Sep 17 00:00:00 2001 From: anatoly Date: Mon, 19 Oct 2015 21:33:56 -0400 Subject: [PATCH] welcome mount --- .gitignore | 14 +++ .hgignore | 12 ++ LICENSE | 214 +++++++++++++++++++++++++++++++++++ README.md | 187 ++++++++++++++++++++++++++++++ dev/dev.clj | 35 ++++++ dev/user.clj | 4 + doc/intro.md | 3 + project.clj | 16 +++ src/mount/mount.clj | 39 +++++++ test/mount/app.clj | 50 ++++++++ test/mount/config.clj | 13 +++ test/mount/nyse.clj | 21 ++++ test/mount/utils/datomic.clj | 11 ++ test/resources/config.edn | 23 ++++ 14 files changed, 642 insertions(+) create mode 100644 .gitignore create mode 100644 .hgignore create mode 100644 LICENSE create mode 100644 README.md create mode 100644 dev/dev.clj create mode 100644 dev/user.clj create mode 100644 doc/intro.md create mode 100644 project.clj create mode 100644 src/mount/mount.clj create mode 100644 test/mount/app.clj create mode 100644 test/mount/config.clj create mode 100644 test/mount/nyse.clj create mode 100644 test/mount/utils/datomic.clj create mode 100644 test/resources/config.edn diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..44e267b --- /dev/null +++ b/.gitignore @@ -0,0 +1,14 @@ +/target +/classes +/checkouts +pom.xml +pom.xml.asc +*.jar +*.class +/.lein-* +/.nrepl-port +*.iml +/.idea +/.lein-repl-history + + diff --git a/.hgignore b/.hgignore new file mode 100644 index 0000000..158f8e1 --- /dev/null +++ b/.hgignore @@ -0,0 +1,12 @@ +syntax: glob +target/** +classes/** +checkouts/** +pom.xml +pom.xml.asc +*.jar +*.class +/.lein-* +/.nrepl-port +.gitignore +.git/** diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..7689f30 --- /dev/null +++ b/LICENSE @@ -0,0 +1,214 @@ +THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC +LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM +CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. + +1. DEFINITIONS + +"Contribution" means: + +a) in the case of the initial Contributor, the initial code and +documentation distributed under this Agreement, and + +b) in the case of each subsequent Contributor: + +i) changes to the Program, and + +ii) additions to the Program; + +where such changes and/or additions to the Program originate from and are +distributed by that particular Contributor. A Contribution 'originates' from +a Contributor if it was added to the Program by such Contributor itself or +anyone acting on such Contributor's behalf. Contributions do not include +additions to the Program which: (i) are separate modules of software +distributed in conjunction with the Program under their own license +agreement, and (ii) are not derivative works of the Program. + +"Contributor" means any person or entity that distributes the Program. + +"Licensed Patents" mean patent claims licensable by a Contributor which are +necessarily infringed by the use or sale of its Contribution alone or when +combined with the Program. + +"Program" means the Contributions distributed in accordance with this +Agreement. + +"Recipient" means anyone who receives the Program under this Agreement, +including all Contributors. + +2. GRANT OF RIGHTS + +a) Subject to the terms of this Agreement, each Contributor hereby grants +Recipient a non-exclusive, worldwide, royalty-free copyright license to +reproduce, prepare derivative works of, publicly display, publicly perform, +distribute and sublicense the Contribution of such Contributor, if any, and +such derivative works, in source code and object code form. + +b) Subject to the terms of this Agreement, each Contributor hereby grants +Recipient a non-exclusive, worldwide, royalty-free patent license under +Licensed Patents to make, use, sell, offer to sell, import and otherwise +transfer the Contribution of such Contributor, if any, in source code and +object code form. This patent license shall apply to the combination of the +Contribution and the Program if, at the time the Contribution is added by the +Contributor, such addition of the Contribution causes such combination to be +covered by the Licensed Patents. The patent license shall not apply to any +other combinations which include the Contribution. No hardware per se is +licensed hereunder. + +c) Recipient understands that although each Contributor grants the licenses +to its Contributions set forth herein, no assurances are provided by any +Contributor that the Program does not infringe the patent or other +intellectual property rights of any other entity. Each Contributor disclaims +any liability to Recipient for claims brought by any other entity based on +infringement of intellectual property rights or otherwise. As a condition to +exercising the rights and licenses granted hereunder, each Recipient hereby +assumes sole responsibility to secure any other intellectual property rights +needed, if any. For example, if a third party patent license is required to +allow Recipient to distribute the Program, it is Recipient's responsibility +to acquire that license before distributing the Program. + +d) Each Contributor represents that to its knowledge it has sufficient +copyright rights in its Contribution, if any, to grant the copyright license +set forth in this Agreement. + +3. REQUIREMENTS + +A Contributor may choose to distribute the Program in object code form under +its own license agreement, provided that: + +a) it complies with the terms and conditions of this Agreement; and + +b) its license agreement: + +i) effectively disclaims on behalf of all Contributors all warranties and +conditions, express and implied, including warranties or conditions of title +and non-infringement, and implied warranties or conditions of merchantability +and fitness for a particular purpose; + +ii) effectively excludes on behalf of all Contributors all liability for +damages, including direct, indirect, special, incidental and consequential +damages, such as lost profits; + +iii) states that any provisions which differ from this Agreement are offered +by that Contributor alone and not by any other party; and + +iv) states that source code for the Program is available from such +Contributor, and informs licensees how to obtain it in a reasonable manner on +or through a medium customarily used for software exchange. + +When the Program is made available in source code form: + +a) it must be made available under this Agreement; and + +b) a copy of this Agreement must be included with each copy of the Program. + +Contributors may not remove or alter any copyright notices contained within +the Program. + +Each Contributor must identify itself as the originator of its Contribution, +if any, in a manner that reasonably allows subsequent Recipients to identify +the originator of the Contribution. + +4. COMMERCIAL DISTRIBUTION + +Commercial distributors of software may accept certain responsibilities with +respect to end users, business partners and the like. While this license is +intended to facilitate the commercial use of the Program, the Contributor who +includes the Program in a commercial product offering should do so in a +manner which does not create potential liability for other Contributors. +Therefore, if a Contributor includes the Program in a commercial product +offering, such Contributor ("Commercial Contributor") hereby agrees to defend +and indemnify every other Contributor ("Indemnified Contributor") against any +losses, damages and costs (collectively "Losses") arising from claims, +lawsuits and other legal actions brought by a third party against the +Indemnified Contributor to the extent caused by the acts or omissions of such +Commercial Contributor in connection with its distribution of the Program in +a commercial product offering. The obligations in this section do not apply +to any claims or Losses relating to any actual or alleged intellectual +property infringement. In order to qualify, an Indemnified Contributor must: +a) promptly notify the Commercial Contributor in writing of such claim, and +b) allow the Commercial Contributor tocontrol, and cooperate with the +Commercial Contributor in, the defense and any related settlement +negotiations. The Indemnified Contributor may participate in any such claim +at its own expense. + +For example, a Contributor might include the Program in a commercial product +offering, Product X. That Contributor is then a Commercial Contributor. If +that Commercial Contributor then makes performance claims, or offers +warranties related to Product X, those performance claims and warranties are +such Commercial Contributor's responsibility alone. Under this section, the +Commercial Contributor would have to defend claims against the other +Contributors related to those performance claims and warranties, and if a +court requires any other Contributor to pay any damages as a result, the +Commercial Contributor must pay those damages. + +5. NO WARRANTY + +EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON +AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER +EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR +CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A +PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the +appropriateness of using and distributing the Program and assumes all risks +associated with its exercise of rights under this Agreement , including but +not limited to the risks and costs of program errors, compliance with +applicable laws, damage to or loss of data, programs or equipment, and +unavailability or interruption of operations. + +6. DISCLAIMER OF LIABILITY + +EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY +CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION +LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE +EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY +OF SUCH DAMAGES. + +7. GENERAL + +If any provision of this Agreement is invalid or unenforceable under +applicable law, it shall not affect the validity or enforceability of the +remainder of the terms of this Agreement, and without further action by the +parties hereto, such provision shall be reformed to the minimum extent +necessary to make such provision valid and enforceable. + +If Recipient institutes patent litigation against any entity (including a +cross-claim or counterclaim in a lawsuit) alleging that the Program itself +(excluding combinations of the Program with other software or hardware) +infringes such Recipient's patent(s), then such Recipient's rights granted +under Section 2(b) shall terminate as of the date such litigation is filed. + +All Recipient's rights under this Agreement shall terminate if it fails to +comply with any of the material terms or conditions of this Agreement and +does not cure such failure in a reasonable period of time after becoming +aware of such noncompliance. If all Recipient's rights under this Agreement +terminate, Recipient agrees to cease use and distribution of the Program as +soon as reasonably practicable. However, Recipient's obligations under this +Agreement and any licenses granted by Recipient relating to the Program shall +continue and survive. + +Everyone is permitted to copy and distribute copies of this Agreement, but in +order to avoid inconsistency the Agreement is copyrighted and may only be +modified in the following manner. The Agreement Steward reserves the right to +publish new versions (including revisions) of this Agreement from time to +time. No one other than the Agreement Steward has the right to modify this +Agreement. The Eclipse Foundation is the initial Agreement Steward. The +Eclipse Foundation may assign the responsibility to serve as the Agreement +Steward to a suitable separate entity. Each new version of the Agreement will +be given a distinguishing version number. The Program (including +Contributions) may always be distributed subject to the version of the +Agreement under which it was received. In addition, after a new version of +the Agreement is published, Contributor may elect to distribute the Program +(including its Contributions) under the new version. Except as expressly +stated in Sections 2(a) and 2(b) above, Recipient receives no rights or +licenses to the intellectual property of any Contributor under this +Agreement, whether expressly, by implication, estoppel or otherwise. All +rights in the Program not expressly granted under this Agreement are +reserved. + +This Agreement is governed by the laws of the State of New York and the +intellectual property laws of the United States of America. No party to this +Agreement will bring a legal action under this Agreement more than one year +after the cause of action arose. Each party waives its rights to a jury trial +in any resulting litigation. diff --git a/README.md b/README.md new file mode 100644 index 0000000..fe39044 --- /dev/null +++ b/README.md @@ -0,0 +1,187 @@ +# mount + +riding side by side with [tools.namespace](https://github.com/clojure/tools.namespace) to manage application state during development. + +## why? + +Clojure is + +* powerful +* simple +* and _fun_ + +Depending on how application state is managed during development, the above three superpowers can either stay, +go somewhat or go completely. + +If Clojure REPL (i.e. `lein repl`, `boot repl`) fired up instantly, the need to reload application state +inside the REPL would go away. But at the moment, and for some time in the future, managing state by making it +reloadable within the same REPL session is important to retain all the Clojure superpowers. + +[Here](http://blog.ndk.io/2014/02/25/clojure-bootstrapping.html) is a good break down on the Clojure REPL +startup time, and it is [not because of JVM](http://blog.ndk.io/2014/02/11/jvm-slow-startup.html). + +`mount` is here to preserve all the Clojure superpowers while making application state enjoyably reloadable. + +There is another Clojure superpower that `mount` is made to retain: Clojure community. +Pull request away, let's solve this thing! + +## how + +```clojure +(require '[mount :refer [defstate]]) +``` + +### Creating State + +Creating state is easy: + +```clojure +(defstate conn :start (create-conn)) +``` + +where `(create-conn)` is defined elsewhere, can be right above it. + +In case this state needs to be cleaned / destryed between reloads, there is also a `:stop` + +```clojure +(defstate conn :start (create-conn) + :stop (disconnect conn)) +``` + +That is pretty much it. But wait, there is more.. this state is a top level being, which means it can be simply +`required` by other namespaces. + +### Using State + +For example let's say an `app` needs a connection above. No problem: + +```clojure +(ns app + (:require [above :refer [conn]])) +``` + +where `above` is an arbitrary namespace that have the above state / connection. + +## Dependencies + +If the whole app is one big application context (or `system`), cross dependencies with a solid dependency graph +is an integral part of the system. + +But if a state is a simple top level being, these beings can coexist with each other and with other +namespaces by being `required` instead. + +If a managing state library requires a whole app buy-in, where everything is a bean or a component, +it is a framework, and dependency graph is usually quite large and complex, +since it has _everything_ (every piece of the application) in it. + +But if stateful things are kept lean and low level (i.e. I/O, queues, etc.), dependency graphs are simple +and small, and everything else is just namespaces and functions: the way it shuold be. + +### Talking States + +There are of course direct dependecies that `mount` respects: + +```clojure +(ns app.config + (:require [mount :refer [defstate]])) + +(defstate app-config + :start (load-config "test/resources/config.edn")) +``` + +this app-config, being top level, can be used in other namespaces, including the ones that create states: + +```clojure +(ns app.database + (:require [mount :refer [defstate]] + [app.config :refer [app-config]])) + +(defstate conn :start (create-connection app-config)) +``` + +[here](https://github.com/tolitius/mount/blob/master/test/mount/nyse.clj) +is an example of Datomic connection that "depends" on the app config. + +## The Importance of Being Reloadable + +`mount` has start and stop functions that will walk all the states created with `defstate` and start / stop them +accordingly: i.e. will call their `:start` and `:stop` defined functions. + +This can be easily hooked up to [tool.namespace](https://github.com/clojure/tools.namespace), to make the whole +application reloadable. Here is a [dev.clj](https://github.com/tolitius/mount/blob/master/dev/dev.clj) as +an example. + +## mount and develop! + +`mount` comes with an example [app](https://github.com/tolitius/mount/blob/master/test/mount/app.clj) +that has two states: + +* config, loaded from the files and refreshed on each `(reset)` +* datamic connection that uses the config to create connection + +### Running New York Stock Exchange + +To try it out, clone `mount`, get to REPL and switch to `(dev)`: + +```clojure +$ lein repl + +user=> (dev) +20:37:29.461 [nREPL-worker-0] INFO mount.config - loading config from test/resources/config.edn +20:37:29.477 [nREPL-worker-0] INFO mount.nyse - creating a connection to datomic: datomic:mem://mount +dev=> +``` + +everything is started and can be played with: + +```clojure +dev=> (create-nyse-schema) +dev=> (add-order "GOOG" 665.51M 665.59M 100) +dev=> (add-order "GOOG" 665.50M 665.58M 300) + +dev=> (find-orders "GOOG") +({:db/id 17592186045418, :order/symbol "GOOG", :order/bid 665.51M, :order/qty 100, :order/offer 665.59M} + {:db/id 17592186045420, :order/symbol "GOOG", :order/bid 665.50M, :order/qty 300, :order/offer 665.58M}) +``` + +once something changed in the code, or you just need to reload everything `(reset)`: + +```clojure +dev=> (reset) +20:38:43.244 [nREPL-worker-1] INFO mount.nyse - disconnecting from datomic:mem://mount +:reloading (mount mount.config mount.nyse mount.utils.datomic mount.app dev) + +20:38:43.287 [nREPL-worker-1] INFO mount.config - loading config from test/resources/config.edn +20:38:43.296 [nREPL-worker-1] INFO mount.nyse - creating a connection to datomic: datomic:mem://mount +:ready +``` + +notice that it stopped and started again. + +Since the schema was not there roght after the start, it is not there now as well: + +```clojure +dev=> (find-orders "GOOG") + +IllegalArgumentExceptionInfo :db.error/not-an-entity Unable to resolve entity: :order/symbol datomic.error/arg (error.clj:57) +``` + +hence the app is in its "clean" state, and ready to rock and roll as right after the REPL started: + +```clojure +dev=> (create-nyse-schema) +dev=> (find-orders "GOOG") +() + +dev=> (add-order "AAPL" 111.712M 111.811M 250) + +dev=> (find-orders "AAPL") +({:db/id 17592186045418, :order/symbol "AAPL", :order/bid 111.712M, :order/qty 250, :order/offer 111.811M}) +``` + +## license + +Copyright © 2015 tolitius + +Distributed under the Eclipse Public License either version 1.0 or (at +your option) any later version. diff --git a/dev/dev.clj b/dev/dev.clj new file mode 100644 index 0000000..21e45e0 --- /dev/null +++ b/dev/dev.clj @@ -0,0 +1,35 @@ +(ns dev + "Tools for interactive development with the REPL. This file should + not be included in a production build of the application." + ;; (:use [cljs.repl :only [repl]] + ;; [cljs.repl.browser :only [repl-env]]) + (:require [clojure.java.io :as io] + [clojure.java.javadoc :refer [javadoc]] + [clojure.pprint :refer [pprint]] + [clojure.reflect :refer [reflect]] + [clojure.repl :refer [apropos dir doc find-doc pst source]] + [clojure.set :as set] + [clojure.string :as str] + [clojure.test :as test] + ;; [clojure.core.async :refer [>!! ! {:state (str `~state) :start `(fn [] (~@start))} + (cond-> df (assoc :stop `(fn [] (~@stop)))))] + `(defonce ~(with-meta state (merge (meta state) s-meta)) + (~@start))))) + +(defn- up [{:keys [ns name start]}] + (intern ns (symbol name) (start))) + +(defn- down [{:keys [stop]}] + (when stop + (stop))) + +(defn- f-states [f] + (->> (all-ns) + (mapcat ns-interns) + (map second) + (filter #(:state (meta %))) + (map (comp f meta)))) + +(defn start [] + (doall + (f-states up))) + +(defn stop [] + (doall + (f-states down))) diff --git a/test/mount/app.clj b/test/mount/app.clj new file mode 100644 index 0000000..f0ca4e8 --- /dev/null +++ b/test/mount/app.clj @@ -0,0 +1,50 @@ +(ns mount.app + (:require [datomic.api :as d] + [mount.utils.datomic :refer [touch]] + [mount.config :refer [app-config]] + [mount.nyse :as nyse])) + +(defn create-schema [conn] + (let [schema [{:db/id #db/id [:db.part/db] + :db/ident :order/symbol + :db/valueType :db.type/string + :db/cardinality :db.cardinality/one + :db/index true + :db.install/_attribute :db.part/db} + + {:db/id #db/id [:db.part/db] + :db/ident :order/bid + :db/valueType :db.type/bigdec + :db/cardinality :db.cardinality/one + :db.install/_attribute :db.part/db} + + {:db/id #db/id [:db.part/db] + :db/ident :order/qty + :db/valueType :db.type/long + :db/cardinality :db.cardinality/one + :db.install/_attribute :db.part/db} + + {:db/id #db/id [:db.part/db] + :db/ident :order/offer + :db/valueType :db.type/bigdec + :db/cardinality :db.cardinality/one + :db.install/_attribute :db.part/db}]] + + @(d/transact conn schema))) + +(defn add-order [ticker bid offer qty] ;; can take connection as param + @(d/transact nyse/conn [{:db/id (d/tempid :db.part/user) + :order/symbol ticker + :order/bid bid + :order/offer offer + :order/qty qty}])) + + +(defn find-orders [ticker] ;; can take connection as param + (let [orders (d/q '[:find ?e :in $ ?ticker + :where [?e :order/symbol ?ticker]] + (d/db nyse/conn) ticker)] + (touch nyse/conn orders))) + +(defn create-nyse-schema [] + (create-schema nyse/conn)) diff --git a/test/mount/config.clj b/test/mount/config.clj new file mode 100644 index 0000000..d270848 --- /dev/null +++ b/test/mount/config.clj @@ -0,0 +1,13 @@ +(ns mount.config + (:require [mount :refer [defstate]] + [clojure.edn :as edn] + [clojure.tools.logging :refer [info]])) + +(defn load-config [path] + (info "loading config from" path) + (-> path + slurp + edn/read-string)) + +(defstate app-config + :start (load-config "test/resources/config.edn")) diff --git a/test/mount/nyse.clj b/test/mount/nyse.clj new file mode 100644 index 0000000..bbbb954 --- /dev/null +++ b/test/mount/nyse.clj @@ -0,0 +1,21 @@ +(ns mount.nyse + (:require [mount :refer [defstate]] + [mount.config :refer [app-config]] + [datomic.api :as d] + [clojure.tools.logging :refer [info]])) + +(defn- new-connection [conf] + (info "conf: " conf) + (let [uri (get-in conf [:datomic :uri])] + (info "creating a connection to datomic:" uri) + (d/create-database uri) + (d/connect uri))) + +(defn disconnect [conf conn] + (let [uri (get-in conf [:datomic :uri])] + (info "disconnecting from " uri) + (.release conn) ;; usually it's no released, here just to illustrate the access to connection on (stop) + (d/delete-database uri))) + +(defstate conn :start (new-connection app-config) + :stop (disconnect app-config conn)) diff --git a/test/mount/utils/datomic.clj b/test/mount/utils/datomic.clj new file mode 100644 index 0000000..ea475e4 --- /dev/null +++ b/test/mount/utils/datomic.clj @@ -0,0 +1,11 @@ +(ns mount.utils.datomic + (:require [datomic.api :as d])) + +(defn entity [conn id] + (d/entity (d/db conn) id)) + +(defn touch [conn results] + "takes 'entity ids' results from a query + e.g. '#{[272678883689461] [272678883689462] [272678883689459] [272678883689457]}'" + (let [e (partial entity conn)] + (map #(-> % first e d/touch) results))) diff --git a/test/resources/config.edn b/test/resources/config.edn new file mode 100644 index 0000000..ef0ca66 --- /dev/null +++ b/test/resources/config.edn @@ -0,0 +1,23 @@ +{:datomic + {:uri "datomic:mem://mount"} + + :h2 + {:classname "org.h2.Driver" + :subprotocol "h2" + :subname "jdbc:h2:mem:mount" + :user "sa" + :password ""} + + :rabbit + {:host "192.168.1.1" + :port 5672 + :api-port 15672 + :node "jabit" + :exchange "foo" + :queue "r-queue" + :routing-key "" + :auto-delete-q? true + :exchange-type "direct" + :vhost "/captoman" + :username "guest" + :password "guest"}}