Merge branch 'add-package-info'

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Christopher Keathley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,6 +1,8 @@
 # Schism
 
-**TODO: Add description**
+Schism provides a simple api for testing partitions between BEAM nodes.
+
+Documentation: [https://hexdocs.pm/schism](https://hexdocs.pm/schism).
 
 ## Installation
 
@@ -10,12 +12,45 @@ by adding `schism` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:schism, "~> 0.1.0"}
+    {:schism, "~> 1.0", only: [:dev, :test]}
   ]
 end
 ```
 
-Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
-and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
-be found at [https://hexdocs.pm/schism](https://hexdocs.pm/schism).
+## Usage
+
+Let's say that we have 5 nodes and we want to test what happens when they
+disconnect from each other. We can use schism like so:
+
+```elixir
+test "netsplits" do
+  [n1, n2, n3, n4, n5] = nodes
+
+  # Partition our nodes
+  Schism.partition([n1, n3])
+  Schism.partition([n4])
+  Schism.partition([n2, n5])
+
+  # Test some stuff...
+
+  # Heal our partitions
+  Schism.heal([n1, n3])
+  Schism.heal([n2, n4, n5])
+end
+```
+
+This api is useful for testing and development in conjunction with tools like
+[local cluster](https://github.com/whitfin/local-cluster) and [propcheck](https://github.com/alfert/propcheck).
+
+It is not recommended that you use this in production.
+
+## Things Schism doesn't do
+
+Schism's reason for existing is to quickly and easily test netsplits between BEAMS
+and it uses a rudimentary trick with cookies to achieve this goal. This is great
+for quickly testing your system against faults.
 
+But because of Schism's simple nature it should not be considered a replacement
+for a more robust suite of tests. It *does not* test failed TCP connections,
+interleaving of messages, race-conditions, clock skew, corruption, or any of
+the other issues you will see in a distributed system.

lib/schism.ex

@@ -1,12 +1,40 @@
 defmodule Schism do
   @moduledoc """
-  Schism allows you to create network partitions in erlang nodes.
+  Schism allows you to create network partitions in erlang nodes without
+  needing to leave elixir.
+
+  Let's say that we have 5 nodes and we want to test what happens when they
+  disconnect from each other. We can use Schism like so:
+
+  ```elixir
+  test "netsplits" do
+    [n1, n2, n3, n4, n5] = nodes
+
+    # Partition our nodes
+    Schism.partition([n1, n3])
+    Schism.partition([n4])
+    Schism.partition([n2, n5])
+
+    # Test some stuff...
+
+    # Heal our partitions
+    Schism.heal([n1, n3])
+    Schism.heal([n2, n4, n5])
+  end
+  ```
+
+  This api is useful for testing and development in conjunction with tools like
+  [local cluster](https://github.com/whitfin/local-cluster) and
+  [propcheck](https://github.com/alfert/propcheck).
   """
 
   @doc """
   Creates a partition amongst a set of nodes. Any nodes in the partition
-  will be able to see each other but no other nodes in the network.
+  will be able to see each other but no other nodes in the network. The
+  partitioned nodes will still be able to see the node that induced the
+  partition. Otherwise we would not be able to heal the partition.
   """
+  @spec partition([Node.t], String.t) :: [Node.t] | none()
   def partition(nodes, id \\ random_string()) when is_binary(id) do
     manager = Node.self()
 
@@ -24,10 +52,14 @@ defmodule Schism do
       # Ensure we can still talk to the node
       :pong = Node.ping(node)
     end
+
+    nodes
   end
 
   @doc """
+  Re-connects the nodes to the cluster.
   """
+  @spec heal([Node.t]) :: [Node.t] | none()
   def heal(nodes) do
     for n <- nodes do
       # Reset the node and ensure we can still talk with it

mix.exs

@@ -4,11 +4,17 @@ defmodule Schism.MixProject do
   def project do
     [
       app: :schism,
-      version: "0.1.0",
+      version: "1.0.0",
       elixir: "~> 1.7",
       start_permanent: Mix.env() == :prod,
       deps: deps(),
       aliases: aliases(),
+
+      description: description(),
+      package: package(),
+      name: "Schism",
+      source_url: "https://github.com/keathley/schism",
+      docs: docs(),
     ]
   end
 
@@ -19,16 +25,38 @@ defmodule Schism.MixProject do
     ]
   end
 
+  # Run "mix help deps" to learn about dependencies.
+  defp deps do
+    [
+      {:local_cluster, "~> 1.0", only: [:dev, :test]},
+      {:ex_doc, "~> 0.19", only: [:dev, :test]},
+    ]
+  end
+
   def aliases do
     [
       test: "test --no-start",
     ]
   end
 
-  # Run "mix help deps" to learn about dependencies.
-  defp deps do
+  def description do
+    """
+    Schism provides a simple api for partitioning networked BEAM instances
+    without having to leave elixir code.
+    """
+  end
+
+  def package do
     [
-      {:local_cluster, "~> 1.0", only: [:dev, :test]},
+      name: "schism",
+      license: ["MIT"],
+      links: %{"GitHub" => "https://github.com/keathley/schism"},
+    ]
+  end
+
+  def docs do
+    [
+      main: "Schism",
     ]
   end
 end

mix.lock

@@ -1,4 +1,9 @@
 %{
+  "earmark": {:hex, :earmark, "1.3.1", "73812f447f7a42358d3ba79283cfa3075a7580a3a2ed457616d6517ac3738cb9", [:mix], [], "hexpm"},
+  "ex_doc": {:hex, :ex_doc, "0.19.3", "3c7b0f02851f5fc13b040e8e925051452e41248f685e40250d7e40b07b9f8c10", [:mix], [{:earmark, "~> 1.2", [hex: :earmark, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.10", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm"},
   "global_flags": {:hex, :global_flags, "1.0.0", "ee6b864979a1fb38d1fbc67838565644baf632212bce864adca21042df036433", [:rebar3], [], "hexpm"},
   "local_cluster": {:hex, :local_cluster, "1.0.4", "3cabf9b267cf276752ee6ceccdbe3a05a2125da1b93c5bb74b586ae4539ebd66", [:mix], [{:global_flags, "~> 1.0", [hex: :global_flags, repo: "hexpm", optional: false]}], "hexpm"},
+  "makeup": {:hex, :makeup, "0.8.0", "9cf32aea71c7fe0a4b2e9246c2c4978f9070257e5c9ce6d4a28ec450a839b55f", [:mix], [{:nimble_parsec, "~> 0.5.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm"},
+  "makeup_elixir": {:hex, :makeup_elixir, "0.13.0", "be7a477997dcac2e48a9d695ec730b2d22418292675c75aa2d34ba0909dcdeda", [:mix], [{:makeup, "~> 0.8", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm"},
+  "nimble_parsec": {:hex, :nimble_parsec, "0.5.0", "90e2eca3d0266e5c53f8fbe0079694740b9c91b6747f2b7e3c5d21966bba8300", [:mix], [], "hexpm"},
 }