node: ensure datadir can be co-inhabited by different instances

This change ensures that nodes started with different Name but same
DataDir values don't use the same nodekey and IPC socket.

1 files changed, 90 insertions, 0 deletions

diff --git a/node/doc.go b/node/doc.go
new file mode 100644
index 000000000..f009e6f85
--- /dev/null
+++ b/node/doc.go
@@ -0,0 +1,90 @@
+// Copyright 2016 The go-ethereum Authors
+// This file is part of the go-ethereum library.
+//
+// The go-ethereum library is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// The go-ethereum library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
+
+/*
+Package node sets up multi-protocol Ethereum nodes.
+
+In the model exposed by this package, a node is a collection of services which use shared
+resources to provide RPC APIs. Services can also offer devp2p protocols, which are wired
+up to the devp2p network when the node instance is started.
+
+
+Resources Managed By Node
+
+All file-system resources used by a node instance are located in a directory called the
+data directory. The location of each resource can be overridden through additional node
+configuration. The data directory is optional. If it is not set and the location of a
+resource is otherwise unspecified, package node will create the resource in memory.
+
+To access to the devp2p network, Node configures and starts p2p.Server. Each host on the
+devp2p network has a unique identifier, the node key. The Node instance persists this key
+across restarts. Node also loads static and trusted node lists and ensures that knowledge
+about other hosts is persisted.
+
+JSON-RPC servers which run HTTP, WebSocket or IPC can be started on a Node. RPC modules
+offered by registered services will be offered on those endpoints. Users can restrict any
+endpoint to a subset of RPC modules. Node itself offers the "debug", "admin" and "web3"
+modules.
+
+Service implementations can open LevelDB databases through the service context. Package
+node chooses the file system location of each database. If the node is configured to run
+without a data directory, databases are opened in memory instead.
+
+Node also creates the shared store of encrypted Ethereum account keys. Services can access
+the account manager through the service context.
+
+
+Sharing Data Directory Among Instances
+
+Multiple node instances can share a single data directory if they have distinct instance
+names (set through the Name config option). Sharing behaviour depends on the type of
+resource.
+
+devp2p-related resources (node key, static/trusted node lists, known hosts database) are
+stored in a directory with the same name as the instance. Thus, multiple node instances
+using the same data directory will store this information in different subdirectories of
+the data directory.
+
+LevelDB databases are also stored within the instance subdirectory. If multiple node
+instances use the same data directory, openening the databases with identical names will
+create one database for each instance.
+
+The account key store is shared among all node instances using the same data directory
+unless its location is changed through the KeyStoreDir configuration option.
+
+
+Data Directory Sharing Example
+
+In this exanple, two node instances named A and B are started with the same data
+directory. Mode instance A opens the database "db", node instance B opens the databases
+"db" and "db-2". The following files will be created in the data directory:
+
+   data-directory/
+        A/
+            nodekey            -- devp2p node key of instance A
+            nodes/             -- devp2p discovery knowledge database of instance A
+            db/                -- LevelDB content for "db"
+        A.ipc                  -- JSON-RPC UNIX domain socket endpoint of instance A
+        B/
+            nodekey            -- devp2p node key of node B
+            nodes/             -- devp2p discovery knowledge database of instance B
+            static-nodes.json  -- devp2p static node list of instance B
+            db/                -- LevelDB content for "db"
+            db-2/              -- LevelDB content for "db-2"
+        B.ipc                  -- JSON-RPC UNIX domain socket endpoint of instance A
+        keystore/              -- account key store, used by both instances
+*/
+package node