github.com/niedbalski/juju@v0.0.0-20190215020005-8ff100488e47/core/doc.go (about)

     1  // Copyright 2015 Canonical Ltd.
     2  // Licensed under the AGPLv3, see LICENCE file for details.
     3  
     4  /*
     5  Package core exists to hold concepts and pure logic pertaining to juju's domain.
     6  We'd call it "model code" if we weren't planning to rename "environ" to "model";
     7  but that'd be quite needlessly confusing, so "core" it is.
     8  
     9  This is a necessarily broad brush; if anything, it's mmost important to be aware
    10  what should *not* go here. In particular:
    11  
    12    * if it makes any reference to MongoDB, it should not be in here.
    13    * if it's in any way concerned with API transport, or serialization, it should
    14      not be in here.
    15    * if it has to do with the *specifics* of any resource *substrate* (compute,
    16      storage, networking, ...) it should not be in here.
    17  
    18  ...and more generally, when adding to core:
    19  
    20    * it's fine to import from any subpackage of "github.com/juju/juju/core"
    21    * but *never* import from any *other* subpackage of "github.com/juju/juju"
    22    * don't you *dare* introduce mutable global state or I will hunt you down
    23    * like a dog
    24  
    25  ...although, of course, *moving* code into core is great, so long as you don't
    26  drag in forbidden concerns as you do so. At first glance, the following packages
    27  are good candidates for near-term corification:
    28  
    29    * constraints (only dependency is instance)
    30    * instance (only dependency is network)
    31    * network (already core-safe)
    32    * watcher-excluding-legacy (only depends on worker[/catacomb])
    33    * worker-excluding-other-subpackages
    34  
    35  ...and these have significant core-worthy content, but will be harder to extract:
    36  
    37    * environs[/config]-excluding-registry
    38    * storage-excluding-registry (depends only on instance and environs/config)
    39    * workload
    40  
    41  ...and, last but most, state, which deserves especially detailed consideration,
    42  because:
    43  
    44    * it is by *far* the largest repository of business logic.
    45    * much of the business logic is horribly entangled with mgo concerns
    46    * plenty of bits -- pure model validation bits, status stuff, unit/machine
    47      assignment rules, probably a thousand more -- will be easy to extract
    48  
    49  ...but plenty of other bits will *not* be easy: in particular, all the business
    50  rules that concern consistency are really tricky, and somewhat dangerous, to
    51  extract, because (while those rules and relationshipps *are* business logic) we
    52  need to be able to *render* them into a mgo/txn representation to ensure DB
    53  consistency. If we just depend on implementing the state bits to match, rather
    54  than *use*, the core logic, we're basically completely screwed.
    55  
    56  The one place we address these concerns is in the core/lease.Token interface,
    57  which includes functionality for communicating with the implementation of
    58  lease.Client currently in play; where the state code which is responsible for
    59  creating a mongo-based client is not entirely unjustified in making use of the
    60  trapdoor to extract mgo.txn operations from lease.Token~s passed back in.
    61  
    62  There's probably some sort of generally-useful abstraction to be extracted there,
    63  but I'm not sure what it is yet.
    64  */
    65  package core