Merge lp:~jderose/filestore/explicit-create into lp:filestore

[Jason Gerard DeRose]

For background, see this bug:

  https://bugs.launchpad.net/filestore/+bug/1163002

The are two interwoven goals here. The first is to force the programmer always to choose between assuming no file-store yet exists in a given parentdir, or assuming a file-store already exists in a given parentdir, with an unforgiving mountain of exceptions and double checks to punish anyone who crosses the streams. Architecturally the previous fuzzy gray area here was a really bad call on my part, and so I'm trying to atone now =)

The second is to cleanly separate out the V0 to V1 upgrade functionality from day to day FileStore functionality. Because the act of creating a FileStore instance could implicitly initialize a file-store layout where there wasn't one before, the upgrade functionality really had to be hooked into FileStore.__init__() and was kind of a mess. But as this gray area has been vanquished, it's now easy to isolate the upgrade functionality from FileStore.__init__().

It's better to do the "soft-upgrade" (basically, moving files/ to files0/) before you create a FileStore instance, which you can now do:

>>> parentdir = '/media/jderose/BigDrive'
>>> m = Migration(parentdir)
>>> m.needs_upgrade() # Soft upgrade if needed, but wont "create" anything
>>> fs = FileStore(parentdir) # Assumes the file-store layout already exists
>>> fs = FileStore.create(parentdir) # The alternative assumption, it does not exist

If `Migration.needs_upgrade()` returns True, then you (likely) have files that need to be re-hashed in order to migrate them from the V0 to the V1 IDs, which you can do by running `dmedia-v0-v1-upgrade`. This can be very time consuming, but can be resumed from where you left off (and the intermediate result will even be synced between your devices).

Anyway, changes include:

* A file-store layout now must always be explicitly initialized, which is done using the new FileStore.create() classmethod:

   FileStore.create(parentdir, store_id=None, copies=1, **kw)

   If path.join(parentdir, '.dmedia') already exists, this method will fail loudly. A big difference between this and the old FileStore.init_dirs() is this classmethod assigns the FileStore an ID (which you can manually provide via *store_id*) and also writes out the "document" to a JSON file, which for an easier migration from V0 is now in 'filestore.json' instead of 'store.json'. So FileStore.create() is taking responsibility for this part rather than letting Dmedia handle it.

   This is a slightly different API than originally discussed in the bug, but there are a few circumstances where manually assigned the ID is handy. For one, unit testing, like to see what happens if you try to connect two physically distinct file-stores that happen to have the same ID. Also, for performance reasons one might want to periodically format a drive, but then initialize the file-store using the previous ID so the ID is stable over time.

   Any additional **kw get included in the filestore.json document. The two that seem handy to me at the moment are `uuid` and `label` (the containing partition's UUID and Label).

* On the other hand, FileStore.__init__() will now fail if the file-store layout does *not* already exist, and has a slightly different signature:

   FileStore.__init__(parentdir, expected_id=None)

   Note that when "loading" an existing file-store, you can't actually change the ID. The optional `expected_id` kwarg tells FileStore.__init__() to *fail* if the ID in filestore.json doesn't match `expected_id`. This is mostly for subprocesses so that they have a more robust way to stay on the same page with the parent process in terms of the currently connect file-stores.

   Also note that previously you could sort of "override" the copies value, but now this can only be provided in FileStore.create(). FileStore.__init__() simply loads these values from filestore.json.

* Added the low-level `_create_filestore()` function that both `FileStore.create()` and `TempFileStore.__init__()` use:

   _create_filestore(parentdir, store_id, copies, **kw)

   It isn't indented as part of the public API just yet, but I think it's a big step forward in terms of the file-store layout initialization being closer to atomic. It's a lot more robust than it was. It creates the layout in temporary directory .dmedia-<STORE_ID>, does everything relative to an open directory descriptor (hooray for Python 3.3), and then at the very last minute renames:

   .dmedia-<STORE_ID> => .dmedia

* FileStore instances (including TempFileStore) now all have a FileStore.doc attribute, which is a Python dict and is the exact Dmedia V1 scheme compliant doc ready to save into CouchDB. This doc is dumped to filestore.json by FileStore.create(), and then is loaded whenever you load an existing file-store with FileStore.__init__()

* Moved all upgrade/migration functionality out of filestore and into the new filestore.migration module; this is much more robust than before and has extensive unit tests

* A bit of sundry cleanup and modernization, of the sort I just can't turn down during a refactor-fest such as this

[James Raymond (jamesmr)]

review: Approve

=== modified file 'benchmark-protocol.py'
--- benchmark-protocol.py	2013-01-13 01:58:52 +0000
+++ benchmark-protocol.py	2013-05-15 00:48:33 +0000
@@ -3,54 +3,35 @@
 import timeit
 
 setup = """
-from base64 import b32encode, b64encode
-from _filestore import fast_b32encode
-
-from filestore import check_id, B32ALPHABET
-from filestore.protocols import Protocol, OldProtocol, MiB
-
-digest = b'N' * 30
-_id = 'GTUK6VPCITPAUSG3FLVNYK7IXEPXWDKGQ4T2X4IUOYXDE232'
-
-new = Protocol(8 * MiB, 240)
-old = OldProtocol(8 * MiB, 240)
-
-leaf_index = 17
-leaf_data = b'S' * 1776
-
-file_size = 31415
-leaf_hashes = b'D' * 30
+from base64 import b64encode
+from dbase32 import db32enc
+from filestore.protocols import VERSION0, VERSION1, make_key
+
+leaf_count = 32  # 256 MiB file, probably a good middle ground
+leaf_hashes = b'B' * (VERSION1.digest_bytes * leaf_count)
+file_size = VERSION1.leaf_size * leaf_count
+key_file_size = make_key(file_size)
 """
 
-N = 50 * 1000
 
-def run(statement):
+def run(statement, K=150):
     t = timeit.Timer(statement, setup)
-    elapsed = t.timeit(N)
-    rate = int(N / elapsed)
+    n = K * 1000
+    elapsed = t.timeit(n)
+    rate = int(n / elapsed)
     print('{:>10,}: {}'.format(rate, statement))
 
 
 print('Executions per second:')
 
-run('b32encode(digest)')
-run('fast_b32encode(digest)')
-run("fast_b32encode(digest).decode('utf-8')")
-
-run('b64encode(digest)')
-run("b64encode(digest).decode('utf-8')")
-run("b64encode(digest).decode('ascii')")
-
-run('check_id(_id)')
-run('set(_id).issubset(B32ALPHABET)')
-run('B32ALPHABET.issuperset(_id)')
-
-run("old._hash_leaf(leaf_index, leaf_data, b'')")
-run("new._hash_leaf(leaf_index, leaf_data, b'')")
-
-run('old._hash_root(file_size, leaf_hashes)')
-run('new._hash_root(file_size, leaf_hashes)')
-run('new.hash_root(file_size, leaf_hashes)')
-
-run('str(4294967295)')
-run("str(4294967295).encode('utf-8')")
+run('VERSION0._hash_root(key_file_size, leaf_hashes)')
+run('VERSION1._hash_root(key_file_size, leaf_hashes)')
+print('')
+run('VERSION0.hash_root(file_size, leaf_hashes)')
+run('VERSION1.hash_root(file_size, leaf_hashes)')
+print('')
+run('b64encode(VERSION0.hash_root(file_size, leaf_hashes))')
+run('  db32enc(VERSION1.hash_root(file_size, leaf_hashes))')
+
+
+

=== modified file 'debian/control'
--- debian/control	2013-02-21 05:20:15 +0000
+++ debian/control	2013-05-15 00:48:33 +0000
@@ -6,7 +6,7 @@
     python3-all-dev (>= 3.3),
     python3-sphinx,
     python3-skein (>= 0.7.1),
-    python3-dbase32 (>= 0.4),
+    python3-dbase32 (>= 0.6),
 Standards-Version: 3.9.3
 X-Python3-Version: >= 3.3
 Homepage: https://launchpad.net/filestore
@@ -15,7 +15,7 @@
 Architecture: any
 Depends: ${python3:Depends}, ${shlibs:Depends}, ${misc:Depends},
     python3-skein (>= 0.7.1),
-    python3-dbase32 (>= 0.4),
+    python3-dbase32 (>= 0.6),
 Description: Dmedia hashing protocol and file layout
  This is the heart of Dmedia.  It has been split out of Dmedia to make it easier
  to review, and in hopes that other apps might use the hashing protocol and

=== modified file 'filestore/__init__.py'
--- filestore/__init__.py	2013-04-28 20:21:18 +0000
+++ filestore/__init__.py	2013-05-15 00:48:33 +0000
@@ -76,17 +76,17 @@
 from os import path
 import io
 import stat
-from base64 import b64encode
+import fcntl
 import json
 from threading import Thread
 from queue import Queue
 from collections import namedtuple
 import logging
-
-from dbase32 import db32enc, isdb32, random_id, DB32ALPHABET
-from dbase32.rfc3548 import isb32, b32enc
-
-from .protocols import TYPE_ERROR, VERSION0
+import time
+
+from dbase32 import db32enc, isdb32, random_id, DB32ALPHABET, RANDOM_B32LEN
+
+from .protocols import TYPE_ERROR
 from .protocols import VERSION1 as PROTOCOL
 
 try:
@@ -111,16 +111,14 @@
 # Handy constants for file layout:
 DOTNAME = '.dmedia'
 
-# V0 Base32 subdir names:
-B32ALPHABET = '234567ABCDEFGHIJKLMNOPQRSTUVWXYZ'
-B32NAMES = tuple(a + b for a in B32ALPHABET for b in B32ALPHABET)
+# Max durability we allow a local, physical location to count for.  This is
+# conservatively at 2 so that a single physical location is never enough (as
+# Dmedia will try to maintain at least 3 copies).
+MAX_COPIES = 2
 
 # V1 Dbase32 subdir names:
 DB32NAMES = tuple(a + b for a in DB32ALPHABET for b in DB32ALPHABET)
 
-# The presense of any of these means a V0, Base32 file layout:
-NAMES_DIFF = tuple(sorted(set(B32NAMES) - set(DB32NAMES)))
-
 # Named tuples:
 ContentHash = namedtuple('ContentHash', 'id file_size leaf_hashes')
 File = namedtuple('File', 'name size mtime')
@@ -790,22 +788,154 @@
 ###############################################
 # Misc functions used by the `FileStore` class:
 
-def ensuredir(d):
-    """
-    Ensure that *d* exists, is a directory, and is not a symlink.
-    """
+
+class Opener:
+    __slots__ = ('dir_fd',)
+
+    def __init__(self, dir_fd):
+        self.dir_fd = dir_fd
+
+    def __call__(self, name, flags):
+        return os.open(name, flags, dir_fd=self.dir_fd)
+
+
+def _mkdir(name, dir_fd):
+    os.mkdir(name, dir_fd=dir_fd)
+    os.chmod(name, 0o777, dir_fd=dir_fd)
+
+
+def _rename(src, dst, dir_fd):
+    os.rename(src, dst, src_dir_fd=dir_fd, dst_dir_fd=dir_fd)
+
+
+def _dumps(obj):
+    return json.dumps(obj,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(',',': '),
+        indent=4,
+    )
+
+
+def _write(name, dir_fd, text):
+    fp = open(name, 'x', opener=Opener(dir_fd))
+    fp.write(text)
+    fp.flush()
+    os.fsync(fp.fileno())
+    os.chmod(fp.fileno(), 0o444)
+    fp.close()
+
+
+def _create_doc(store_id, copies, **kw):
+    if not isinstance(store_id, str):
+        raise TypeError(
+            TYPE_ERROR.format('store_id', str, type(store_id), store_id)
+        )
+    if len(store_id) != RANDOM_B32LEN:
+        raise ValueError('len(store_id) is {}, need {}: {!r}'.format(
+                len(store_id), RANDOM_B32LEN, store_id)
+        )
+    if not isdb32(store_id):
+        raise ValueError('store_id: invalid Dbase32 ID: {!r}'.format(store_id))
+    if not isinstance(copies, int):
+        raise TypeError(
+            TYPE_ERROR.format('copies', int, type(copies), copies)
+        )
+    if not (0 <= copies <= MAX_COPIES):
+        raise ValueError(
+            'copies is {}, need 0 <= copies <= {}'.format(copies, MAX_COPIES)
+        )
+    doc = {
+        '_id': store_id,
+        'time': time.time(),
+        'type': 'dmedia/store',
+        'plugin': 'filestore',
+        'copies': copies,
+    }
+    for (key, value) in kw.items():
+        doc.setdefault(key, value)
+    return doc
+
+
+def check_doc(doc, expected_id=None):
+    if not isinstance(doc, dict):
+        raise TypeError(
+            TYPE_ERROR.format('doc', dict, type(doc), doc)
+        )
+    _id = doc['_id']
+    if not isinstance(_id, str):
+        raise TypeError(
+            TYPE_ERROR.format("doc['_id']", str, type(_id), _id)
+        )
+    if len(_id) != RANDOM_B32LEN:
+        raise ValueError("len(doc['_id']) is {}, need {}: {!r}".format(
+                len(_id), RANDOM_B32LEN, _id)
+        )
+    if not isdb32(_id):
+        raise ValueError(
+            "doc['_id'] is not a valid Dbase32 ID: {!r}".format(_id)
+        )
+    if not (expected_id is None or expected_id == _id):
+        raise ValueError(
+            "doc['_id']: expected {!r}; got {!r}".format(expected_id, _id)
+        )
+    copies = doc['copies']
+    if not isinstance(copies, int):
+        raise TypeError(
+            TYPE_ERROR.format("doc['copies']", int, type(copies), copies)
+        )
+    if not (0 <= copies <= MAX_COPIES):
+        raise ValueError(
+            "doc['copies'] is {}, need 0 <= doc['copies'] <= {}".format(
+                    copies, MAX_COPIES)
+        )
+    _type = doc['type']
+    if _type != 'dmedia/store':
+        raise ValueError(
+            "doc['type'] is {!r}, must be 'dmedia/store'".format(_type)
+        )
+    return doc
+
+
+def _check_parentdir(parentdir):
+    parentdir = check_path(parentdir)
+    if DOTNAME in parentdir.split(os.sep):
+        raise NestedParent(parentdir, DOTNAME)
+    if not path.isdir(parentdir):
+        raise ValueError('parentdir not a directory: {!r}'.format(parentdir))
+    return parentdir
+
+
+def _create_filestore(parentdir, store_id, copies, **kw):
+    """
+    Low level function for creating a Dbase32, V1+ FileStore layout.
+
+    Please use `FileStore.create()` instead of this function
+
+    This is not regarded as part of the public FileStore API and may break
+    without warning.
+    """
+    dir_fd = os.open(parentdir, os.O_DIRECTORY)
     try:
-        os.mkdir(d)
-        return True
-    except OSError:
-        mode = os.lstat(d).st_mode
-        if stat.S_ISLNK(mode):
-            raise ValueError(
-                '{!r} is symlink to {!r}'.format(d, os.readlink(d))
-            )
-        if not stat.S_ISDIR(mode):
-            raise ValueError('not a directory: {!r}'.format(d))
-        return False
+        doc = _create_doc(store_id, copies, **kw)
+        tmpname = '-'.join([DOTNAME, store_id])
+
+        # Create all the directories:
+        _mkdir(tmpname, dir_fd)
+        for name in ('files', 'partial', 'corrupt', 'tmp'):
+            _mkdir(path.join(tmpname, name), dir_fd)
+        for name in DB32NAMES:
+            _mkdir(path.join(tmpname, 'files', name), dir_fd)
+
+        # Write the two files:
+        _write(path.join(tmpname, 'README.txt'), dir_fd, README)
+        _write(path.join(tmpname, 'filestore.json'), dir_fd, _dumps(doc))
+
+        # Rename to the final directory name, return doc:
+        _rename(tmpname, DOTNAME, dir_fd)
+        return doc
+    finally:
+        os.close(dir_fd)
 
 
 def statvfs(pathname):
@@ -830,98 +960,6 @@
     return StatVFS(size, used, avail, readonly, st.f_frsize)
 
 
-def is_v0_files(files):
-    for name in NAMES_DIFF:
-        if path.isdir(path.join(files, name)):
-            return True
-    return False
-
-
-def dumps(obj):
-    return json.dumps(obj,
-        ensure_ascii=False,
-        sort_keys=True,
-        separators=(',',': '),
-        indent=4,
-    )
-
-
-def migrate_store_doc(basedir):
-    store = path.join(basedir, 'store.json')
-    store0 = path.join(basedir, 'store0.json')
-    try:
-        doc = json.load(open(store, 'r'))
-    except FileNotFoundError:
-        log.error("'store.json' does not exist in %r", basedir)
-        return False
-
-    if path.exists(store0):
-        raise Exception("'store0.json' already exists in {!r}".format(basedir))
-
-    log.warning("Moving V0 'store.json' to 'store0.json' in %r", basedir)
-    os.rename(store, store0)
-
-    from dbase32.rfc3548 import b32dec
-    assert doc.get('migrated') is None
-    old_id = doc['_id']
-    new_id = db32enc(b32dec(old_id))
-    log.warning('Migrating FileStore ID from %r to %r in %r',
-            old_id, new_id, basedir)
-    doc['_id'] = new_id
-    doc['migrated'] = True
-    text = dumps(doc)
-    tmp = path.join(basedir, 'store.json.' + random_id())
-    fp = open(tmp, 'x')
-    fp.write(text)
-    fp.flush()
-    os.fsync(fp.fileno())
-    os.chmod(fp.fileno(), 0o444)
-    fp.close()
-    os.rename(tmp, store)
-    return True
-
-
-###################################################
-# The `Migration` class use for V0 => V1 migration:
-
-class Migration:
-    def __init__(self, fs):
-        assert isinstance(fs, FileStore)
-        self.fs = fs
-        self.files0 = fs.join('files0')
-        assert path.isdir(self.files0)
-
-    def __iter__(self):
-        for prefix in B32NAMES:
-            subdir = path.join(self.files0, prefix)
-            for name in sorted(os.listdir(subdir)):
-                src = path.join(subdir, name)     
-                v0_id = prefix + name       
-                assert path.isfile(src) or path.islink(src)
-                assert isb32(v0_id) and len(v0_id) == 48
-
-                if path.islink(src):
-                    log.info('Reading symlink %r', src)
-                    yield (v0_id, os.readlink(src), None)
-                else:
-                    src_fp = open(src, 'rb')
-                    h0 = Hasher(protocol=VERSION0, enc=b32enc)
-                    h1 = Hasher()
-                    for leaf in reader_iter(src_fp):
-                        h0.hash_leaf(leaf)
-                        h1.hash_leaf(leaf)
-                    ch0 = h0.content_hash()
-                    ch1 = h1.content_hash()
-                    assert isdb32(ch1.id)
-                    if ch0.id != v0_id:
-                        yield (v0_id, None, None)
-                    else:
-                        dst = self.fs.path(ch1.id)
-                        log.info('Moving %r to %r', src, dst)
-                        os.rename(src, dst)
-                        os.symlink(ch1.id, src)
-                        yield (v0_id, ch1.id, ch1)
-
 
 ########################
 # The `FileStore` class:
@@ -947,50 +985,54 @@
            us to provide even stronger data durability guarantees
     """
 
-    def __init__(self, parentdir, _id=None, copies=0):
+    dir_fd = None
+
+    @classmethod
+    def create(cls, parentdir, store_id=None, copies=1, **kw):
+        parentdir = _check_parentdir(parentdir)
+        dotdir = path.join(parentdir, DOTNAME)
+        if path.exists(dotdir):
+            raise ValueError(
+                'Cannot create FileStore, dotdir exists: {!r}'.format(dotdir)
+            )
+        store_id = (random_id() if store_id is None else store_id)
+        _create_filestore(parentdir, store_id, copies, **kw)
+        return cls(parentdir, store_id)
+
+    def __init__(self, parentdir, expected_id=None):
         """
         Initialize.
 
-        :param parentdir: directory for file store, eg ``'/home/jderose'``
-        :param dotname: name of control directory, default is ``'.dmedia'``
+        :param parentdir: directory for file store, eg ``'/media/MyDrive'``
+        :param excepted_id: if provided, an exception is raised if the ID loaded
+            from the ``'filestore.json'`` file doesn't match
         """
-        self.parentdir = check_path(parentdir)
+        self.parentdir = _check_parentdir(parentdir)
         self.basedir = path.join(self.parentdir, DOTNAME)
+        self.dir_fd = os.open(self.basedir, os.O_DIRECTORY |  os.O_NOFOLLOW)
+        fcntl.flock(self.dir_fd, fcntl.LOCK_SH | fcntl.LOCK_NB)
+        fp = open('filestore.json', 'r', opener=self)
+        self.doc = check_doc(json.load(fp), expected_id)
+        self.id = self.doc['_id']
+        self.copies = self.doc['copies']
+
+        # FIXME: Probably don't need this once we raname relative to dir_fd:
         self.tmp = path.join(self.basedir, 'tmp')
-        self.id = _id
-        self.copies = copies
-
-        # Make sure parentdir isn't nested in another FileStore:
-        if DOTNAME in self.parentdir.split(os.sep):
-            raise NestedParent(self.parentdir, DOTNAME)
-
-        # Make sure parentdir is a directory:
-        if not path.isdir(self.parentdir):
-            raise ValueError('{}.parentdir not a directory: {!r}'.format(
-                self.__class__.__name__, self.parentdir)
-            )
-
-        files = self.join('files')
-        files0 = self.join('files0')
-
-        # If basedir doesn't exist, create it and initialize all dirs in layout:
-        if ensuredir(self.basedir):
-            log.info('Initalizing FileStore in %r', self.basedir)
-            self.init_dirs()
-        elif is_v0_files(files):
-            if path.exists(files0):
-                raise Exception(
-                    "'files' is V0 layout but 'files0' exists in {!r}".format(self.basedir)
-                )
-            log.warning("Moving V0 'files' to 'files0' in %r", self.basedir)
-            os.rename(files, files0)
-            self.init_dirs()
-            migrate_store_doc(self.basedir)
-
-        self.needs_migration = path.isdir(files0)
+
+    def __del__(self):
+        if self.dir_fd is not None:
+            os.close(self.dir_fd)
+
+    def __call__(self, name, flags):
+        """
+        As a callable, use a `FileStore` as an opener for ``os.open()``.
+        """
+        return os.open(name, flags, dir_fd=self.dir_fd)
 
     def __repr__(self):
-        return '{}({!r})'.format(self.__class__.__name__, self.parentdir)
+        return '{}({!r}, {!r})'.format(
+            self.__class__.__name__, self.parentdir, self.id
+        )
 
     def __iter__(self):
         """
@@ -1021,26 +1063,39 @@
                 if stat.S_ISREG(st.st_mode) and st.st_size > 0:
                     yield Stat(_id, fullname, st.st_size, st.st_mtime)
 
-    def init_dirs(self):
-        """
-        Creates the needed subdirectories inside the control directory.
-
-        `FileStore.__init__()` automatically calls this if the control directory
-        does not yet exists.
-        """
-        os.chmod(self.basedir, 0o777)
-        for name in ('files', 'partial', 'corrupt', 'tmp'):
-            d = path.join(self.basedir, name)
-            ensuredir(d)
-            os.chmod(d, 0o777)
+    def _check_dir(self, name):
+        assert path.normpath(name) == name
+        assert not path.isabs(name)
+        st = os.stat(name, dir_fd=self.dir_fd, follow_symlinks=False)
+        if not stat.S_ISDIR(st.st_mode):
+            raise ValueError(
+                '{!r} not a directory in {!r}'.format(name, self.basedir)
+            )
+        if stat.S_IMODE(st.st_mode) != 0o777:
+            raise ValueError(
+                'Directory {!r} mode not 0777 in {!r}'.format(name, self.basedir)
+            )
+
+    def _check_file(self, name):
+        assert path.normpath(name) == name
+        assert not path.isabs(name)
+        st = os.stat(name, dir_fd=self.dir_fd, follow_symlinks=False)
+        if not stat.S_ISREG(st.st_mode):
+            raise ValueError(
+                '{!r} not a file in {!r}'.format(name, self.basedir)
+            )
+        if stat.S_IMODE(st.st_mode) != 0o444:
+            raise ValueError(
+                'File {!r} mode not 0444 in {!r}'.format(name, self.basedir)
+            )
+
+    def check_layout(self):
+        for name in ('files', 'tmp', 'partial', 'corrupt'):
+            self._check_dir(name)
         for name in DB32NAMES:
-            d = path.join(self.basedir, 'files', name)
-            ensuredir(d)
-            os.chmod(d, 0o777)
-        f = path.join(self.basedir, 'README.txt')
-        if not path.exists(f):
-            open(f, 'wt').write(README)
-            os.chmod(f, stat.S_IRUSR | stat.S_IRGRP | stat.S_IROTH)
+            self._check_dir(path.join('files', name))
+        for name in ('README.txt', 'filestore.json'):
+            self._check_file(name)
 
     def statvfs(self):
         """
@@ -1300,6 +1355,7 @@
         this method rather than letting boto compute the md5 hash itself.
         """
         import hashlib
+        from base64 import b64encode
         md5 = hashlib.md5()
         for leaf in self.verify_iter2(_id):
             md5.update(leaf.data)

=== added file 'filestore/migration.py'
--- filestore/migration.py	1970-01-01 00:00:00 +0000
+++ filestore/migration.py	2013-05-15 00:48:33 +0000
@@ -0,0 +1,281 @@
+# filestore: Dmedia hashing protocol and file layout
+# Copyright (C) 2013 Novacut Inc
+#
+# This file is part of `filestore`.
+#
+# `filestore` is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option) any
+# later version.
+#
+# `filestore` 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 Affero General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Affero General Public License along
+# with `filestore`.  If not, see <http://www.gnu.org/licenses/>.
+#
+# Authors:
+#   Jason Gerard DeRose <[e-mail]>
+
+"""
+Migrate a V0 layout to V1, rehash to map V0 to V1 IDs.
+"""
+
+import os
+from os import path
+from copy import deepcopy
+import json
+import time
+import logging
+
+import dbase32
+from dbase32 import rfc3548
+
+from . import check_doc, reader_iter, Hasher, DB32NAMES, README
+from . import _check_parentdir, _create_doc, _dumps
+from .misc import load_data, write_files
+from .protocols import VERSION0
+
+
+log = logging.getLogger()
+
+# V0 Base32 subdir names:
+B32ALPHABET = '234567ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+B32NAMES = tuple(a + b for a in B32ALPHABET for b in B32ALPHABET)
+
+# The presense of any of these means a V0, Base32 file layout:
+NAMES_DIFF = tuple(sorted(set(B32NAMES) - set(DB32NAMES)))
+
+
+def is_v0_files(files):
+    for name in NAMES_DIFF:
+        if path.isdir(path.join(files, name)):
+            return True
+    return False
+
+
+def b32_to_db32(_id):
+    """
+    Re-encode an ID from Base32 to Dbase32.
+
+    >>> b32_to_db32('5Q2VGOCRKWGDCSJOHDMXYFCE')
+    'WJTO9H5KDP965LCHA6FQR857'
+
+    """
+    return dbase32.db32enc(rfc3548.b32dec(_id))
+
+
+def v0_doc_to_v1(old):
+    assert isinstance(old, dict)
+    new = deepcopy(old)
+    new['_id'] = b32_to_db32(old['_id'])
+    new['type'] = 'dmedia/store'
+    new['plugin'] = 'filestore'
+    return check_doc(new)
+
+
+def open_file(fullname):
+    try:
+        return open(fullname, 'r')
+    except FileNotFoundError:
+        pass
+
+
+def load_doc(fullname):
+    try:
+        return json.load(open(fullname, 'r'))
+    except (FileNotFoundError, ValueError):
+        pass
+
+
+class Migration:
+    def __init__(self, parentdir):
+        self.parentdir = _check_parentdir(parentdir)
+        self.basedir = path.join(self.parentdir, '.dmedia')
+        self.files = self.join('files')
+        self.files0 = self.join('files0')
+        self.store = self.join('store.json')
+        self.store0 = self.join('store0.json')
+        self.filestore = self.join('filestore.json')
+
+    def __iter__(self):
+        if not self.needs_migration():
+            return
+        for prefix in B32NAMES:
+            subdir = path.join(self.files0, prefix)
+            for name in sorted(os.listdir(subdir)):
+                src = path.join(subdir, name)     
+                v0_id = prefix + name       
+                assert path.isfile(src) or path.islink(src)
+                assert rfc3548.isb32(v0_id) and len(v0_id) == 48
+
+                if path.islink(src):
+                    log.info('Reading symlink %r', src)
+                    yield (v0_id, os.readlink(src), None)
+                else:
+                    src_fp = open(src, 'rb')
+                    h0 = Hasher(protocol=VERSION0, enc=rfc3548.b32enc)
+                    h1 = Hasher()
+                    for leaf in reader_iter(src_fp):
+                        h0.hash_leaf(leaf)
+                        h1.hash_leaf(leaf)
+                    ch0 = h0.content_hash()
+                    ch1 = h1.content_hash()
+                    assert dbase32.isdb32(ch1.id)
+                    if ch0.id != v0_id:
+                        yield (v0_id, None, None)
+                    else:
+                        dst = self.v1_path(ch1.id)
+                        log.info('Moving %r to %r', src, dst)
+                        os.rename(src, dst)
+                        os.symlink(ch1.id, src)
+                        yield (v0_id, ch1.id, ch1)
+
+    def needs_migration(self):
+        if not path.isdir(self.basedir):
+            return False
+        self.write_v1_doc_if_needed()
+        if self.move_files_if_needed():
+            return True
+        return path.isdir(self.files0)
+
+    def build_v0_simulation(self):
+        os.mkdir(self.basedir)
+        os.chmod(self.basedir, 0o777)
+        for name in ('partial', 'corrupt', 'tmp'):
+            self.mkdir(name)
+        self.create_v0_files()
+        self.write('README.txt', README)
+        doc = {
+            '_id': rfc3548.random_id(),
+            'copies': 1, 
+            'plugin': 'filestore', 
+            'time': time.time(), 
+            'type': 'dmedia/store'
+        }
+        self.write('store.json', _dumps(doc))
+        V0 = load_data('V0')
+        write_files(self.basedir, VERSION0)
+        for (key, _id) in V0['root_hashes'].items():
+            src = self.join(key)
+            dst = self.path(_id)
+            os.rename(src, dst)
+            os.chmod(dst, 0o444)
+        return doc
+
+    def join(self, *parts):
+        if not parts:
+            raise ValueError('Cannot have empty parts')
+        return path.join(self.basedir, *parts)
+
+    def mkdir(self, *parts):
+        fullname = self.join(*parts)
+        os.mkdir(fullname)
+        os.chmod(fullname, 0o777)
+        return fullname
+
+    def write(self, name, text):
+        fullname = self.join(name)
+        fp = open(fullname, 'x')
+        fp.write(text)
+        fp.flush()
+        os.fsync(fp.fileno())
+        os.chmod(fp.fileno(), 0o444)
+        fp.close()
+        return fullname
+
+    def load_v0_doc(self):
+        # Hack: as we switched from 'store.json' to 'filestore.json' after the
+        # initial migration functionality landed in 13.05, the old V0 doc might
+        # be in the 'store0.json' file:
+        fp = open_file(self.store0) or open_file(self.store)
+        if fp is None:
+            return
+        try:
+            return json.load(fp)
+        except ValueError:
+            pass        
+
+    def get_v1_doc(self):
+        # If store0.json is presest, it should always be a V0, Base32 doc:
+        old = load_doc(self.store0)
+        if old is not None:
+            return v0_doc_to_v1(old)
+
+        # If only store.json is presest, there are a few scenarios:
+        old = load_doc(self.store)
+        if old is not None:
+            old_id = old['_id']
+            # This scenario is always clear-cut:
+            if not dbase32.isdb32(old_id):
+                return v0_doc_to_v1(old)
+            # Also clear-cut, but 'migration' flag only in 13.05 daily builds:
+            if old.get('migrated') is True or not rfc3548.isb32(old_id):
+                old['type'] = 'dmedia/store'
+                old['plugin'] = 'filestore'
+                old.pop('migrated', None)
+                return check_doc(old)
+            # High chance of being correct, but possible for it to be wrong:
+            return v0_doc_to_v1(old)
+
+        # Otherwise create a new V1 doc, without any migration:
+        return _create_doc(dbase32.random_id(), 1)
+
+    def write_v1_doc_if_needed(self):
+        if path.isfile(self.filestore):
+            return False
+        doc = self.get_v1_doc()
+        self.write('filestore.json', _dumps(doc))
+        assert path.isfile(self.filestore)
+        return True
+
+    def path(self, _id):
+        assert isinstance(_id, str)
+        assert rfc3548.isb32(_id) or dbase32.isdb32(_id)
+        assert len(_id) == 48
+        return self.join('files', _id[:2], _id[2:])
+
+    def v0_path(self, v0_id):
+        assert isinstance(v0_id, str)
+        assert rfc3548.isb32(v0_id)
+        assert len(v0_id) == 48
+        return self.join('files0', v0_id[:2], v0_id[2:])
+
+    def v1_path(self, v1_id):
+        assert isinstance(v1_id, str)
+        assert dbase32.isdb32(v1_id)
+        assert len(v1_id) == 48
+        return self.join('files', v1_id[:2], v1_id[2:])
+
+    def create_v0_files(self):
+        """
+        For testing or reversing the migration, create the V0 layout:
+        """
+        self.mkdir('files')
+        for name in B32NAMES:
+            self.mkdir('files', name)
+
+    def create_v1_files(self):
+        """
+        After moving a V0 files to files0, we need to create a correct V1 files.
+        """
+        self.mkdir('files')
+        for name in DB32NAMES:
+            self.mkdir('files', name)
+
+    def move_files_if_needed(self):
+        if is_v0_files(self.files):
+            self.move_v0_files_to_files0()
+            return True
+        if not path.isdir(self.files):
+            self.create_v1_files()
+        return False  
+
+    def move_v0_files_to_files0(self):
+        assert is_v0_files(self.files)
+        assert not path.exists(self.files0)
+        log.warning('Moving V0 files/ to files0/ in %r', self.basedir)
+        os.rename(self.files, self.files0)
+        self.create_v1_files()

=== modified file 'filestore/misc.py'
--- filestore/misc.py	2013-04-28 17:02:28 +0000
+++ filestore/misc.py	2013-05-15 00:48:33 +0000
@@ -30,10 +30,10 @@
 from hashlib import md5
 import binascii
 
-from dbase32 import db32enc
+from dbase32 import db32enc, random_id
 
 from .protocols import PERS_LEAF, PERS_ROOT, VERSION1
-from . import FileStore
+from . import FileStore, _create_filestore
 
 
 DATADIR = path.join(path.dirname(path.abspath(__file__)), 'data')
@@ -159,19 +159,27 @@
 
     For example:
 
-    >>> fs = TempFileStore('hello', 3)
+    >>> fs = TempFileStore('39AY39AY39AY39AY39AY39AY', 2)
     >>> fs.id
-    'hello'
+    '39AY39AY39AY39AY39AY39AY'
     >>> fs.copies
-    3
+    2
 
     """
-    def __init__(self, _id=None, copies=0):
+
+    @classmethod
+    def create(cls, store_id=None, copies=1, **kw):
+        return cls(store_id, copies, **kw)
+
+    def __init__(self, store_id=None, copies=1, **kw):
         parentdir = tempfile.mkdtemp(prefix='TempFileStore.')
-        super().__init__(parentdir, _id, copies)
-        assert self.parentdir is parentdir
+        store_id = (random_id() if store_id is None else store_id)
+        _create_filestore(parentdir, store_id, copies, **kw)
+        super().__init__(parentdir, store_id)
+        assert self.parentdir == parentdir
 
     def __del__(self):
+        super().__del__()
         if path.isdir(self.parentdir):
             shutil.rmtree(self.parentdir)
 

=== modified file 'filestore/tests/__init__.py'
--- filestore/tests/__init__.py	2013-04-28 18:11:23 +0000
+++ filestore/tests/__init__.py	2013-05-15 00:48:33 +0000
@@ -33,6 +33,8 @@
 import shutil
 import json
 from random import SystemRandom
+import time
+from uuid import uuid4
 
 from _skein import skein512
 from dbase32 import isdb32, db32enc, random_id
@@ -45,13 +47,6 @@
 random = SystemRandom()
 TYPE_ERROR = '{}: need a {!r}; got a {!r}: {!r}'
 
-B32NAMES = []
-for a in filestore.B32ALPHABET:
-    for b in filestore.B32ALPHABET:
-        B32NAMES.append(a + b)
-B32NAMES.sort()
-B32NAMES = tuple(B32NAMES)
-
 
 # Sample file:
 LEAVES = (
@@ -99,11 +94,21 @@
             shutil.rmtree(self.dir)
             self.dir = None
 
+    def chmod(self, mode, *parts):
+        p = self.join(*parts)
+        os.chmod(p, mode)
+        return p
+
     def mkdir(self, *parts):
         d = self.join(*parts)
         os.mkdir(d)
         return d
 
+    def rmdir(self, *parts):
+        d = self.join(*parts)
+        os.rmdir(d)
+        return d
+
     def makedirs(self, *parts):
         d = self.join(*parts)
         if not path.exists(d):
@@ -116,6 +121,17 @@
         open(f, 'xb').close()
         return f
 
+    def remove(self, *parts):
+        f = self.join(*parts)
+        os.remove(f)
+        return f
+
+    def symlink(self, target, *parts):
+        link = self.join(*parts)
+        os.symlink(target, link)
+        assert path.islink(link)
+        return link
+
     def write(self, content, *parts):
         d = self.makedirs(*parts[:-1])
         f = self.join(*parts)
@@ -299,27 +315,6 @@
         self.assertIsInstance(filestore.DOTNAME, str)
         self.assertTrue(filestore.DOTNAME.startswith('.'))
 
-    def test_B32ALPHABET(self):
-        self.assertIsInstance(filestore.B32ALPHABET, str)
-        self.assertEqual(len(filestore.B32ALPHABET), 32)
-        self.assertEqual(len(set(filestore.B32ALPHABET)), 32)
-        self.assertEqual(filestore.B32ALPHABET,
-            ''.join(sorted(filestore.B32ALPHABET))
-        )
-
-    def test_B32NAMES(self):
-        self.assertIsInstance(filestore.B32NAMES, tuple)
-        self.assertEqual(len(filestore.B32NAMES), 1024)
-        self.assertEqual(len(set(filestore.B32NAMES)), 1024)
-        self.assertEqual(filestore.B32NAMES,
-            tuple(sorted(filestore.B32NAMES))
-        )
-        for name in filestore.B32NAMES:
-            self.assertIsInstance(name, str)
-            self.assertEqual(len(name), 2)
-            self.assertTrue(name.isupper() or name.isnumeric())
-            self.assertTrue(set(name).issubset(filestore.B32ALPHABET))
-
     def test_DB32ALPHABET(self):
         self.assertIsInstance(filestore.DB32ALPHABET, str)
         self.assertEqual(len(filestore.DB32ALPHABET), 32)
@@ -341,20 +336,6 @@
             self.assertTrue(name.isupper() or name.isnumeric())
             self.assertTrue(set(name).issubset(filestore.DB32ALPHABET))
 
-    def test_NAMES_DIFF(self):
-        self.assertIsInstance(filestore.NAMES_DIFF, tuple)
-        self.assertEqual(len(filestore.NAMES_DIFF), 124)
-        self.assertEqual(len(set(filestore.NAMES_DIFF)), 124)
-        self.assertEqual(filestore.NAMES_DIFF,
-            tuple(sorted(filestore.NAMES_DIFF))
-        )
-        for name in filestore.NAMES_DIFF:
-            self.assertIsInstance(name, str)
-            self.assertEqual(len(name), 2)
-            self.assertTrue(name.isupper() or name.isnumeric())
-            self.assertIn(name, filestore.B32NAMES)
-            self.assertNotIn(name, filestore.DB32NAMES)
-
 
 class TestFunctions(TestCase):
     def test_hash_leaf(self):
@@ -1053,9 +1034,9 @@
     def test_batch_import_iter(self):
         batch = filestore.Batch(tuple(), 0, 0)
         tmp1 = TempDir()
-        fs1 = filestore.FileStore(tmp1.dir)
+        fs1 = filestore.FileStore.create(tmp1.dir)
         tmp2 = TempDir()
-        fs2 = filestore.FileStore(tmp2.dir)
+        fs2 = filestore.FileStore.create(tmp2.dir)
 
         # Test with wrong batch type
         b = (tuple(), 0, 0)
@@ -1133,9 +1114,9 @@
         cb = Callback()
         batch = filestore.Batch(tuple(), 0, 0)
         tmp1 = TempDir()
-        fs1 = filestore.FileStore(tmp1.dir)
+        fs1 = filestore.FileStore.create(tmp1.dir)
         tmp2 = TempDir()
-        fs2 = filestore.FileStore(tmp2.dir)
+        fs2 = filestore.FileStore.create(tmp2.dir)
         self.assertEqual(
             list(filestore.batch_import_iter(batch, fs1, fs2, callback=cb)),
             []
@@ -1228,49 +1209,577 @@
             self.assertIsInstance(ch, filestore.ContentHash)
             self.assertEqual(ch.id, vectors['root_hashes'][name])
 
-    def test_ensuredir(self):
-        f = filestore.ensuredir
-        tmp = TempDir()
-
-        # Test that os.makedirs() is not used:
-        d = tmp.join('foo', 'bar')
+    def test_create_doc(self):
+        # Bad `store_id` type:
+        bad_id = random_id().encode('utf-8')
+        with self.assertRaises(TypeError) as cm:
+            filestore._create_doc(bad_id, 1)
+        self.assertEqual(
+            str(cm.exception),
+            TYPE_ERROR.format('store_id', str, bytes, bad_id)
+        )
+
+        # Bad `store_id` length:
+        bad_id = random_id(10)
+        with self.assertRaises(ValueError) as cm:
+            filestore._create_doc(bad_id, 1)
+        self.assertEqual(
+            str(cm.exception),
+            'len(store_id) is 16, need 24: {!r}'.format(bad_id)
+        )
+
+        # `store_id` is not valid Dbase32 ID:
+        bad_id = 'Z' * 24
+        with self.assertRaises(ValueError) as cm:
+            filestore._create_doc(bad_id, 1)
+        self.assertEqual(
+            str(cm.exception),
+            "store_id: invalid Dbase32 ID: 'ZZZZZZZZZZZZZZZZZZZZZZZZ'"
+        )
+
+        # Bad `copies` type:
+        good_id = random_id()
+        with self.assertRaises(TypeError) as cm:
+            filestore._create_doc(good_id, 1.0)
+        self.assertEqual(
+            str(cm.exception),
+            TYPE_ERROR.format('copies', int, float, 1.0)
+        )
+        with self.assertRaises(TypeError) as cm:
+            filestore._create_doc(good_id, '1')
+        self.assertEqual(
+            str(cm.exception),
+            TYPE_ERROR.format('copies', int, str, '1')
+        )
+
+        # copies < 0:
+        with self.assertRaises(ValueError) as cm:
+            filestore._create_doc(good_id, -1)
+        self.assertEqual(
+            str(cm.exception),
+            'copies is -1, need 0 <= copies <= 2'
+        )
+
+        # copies > 2:
+        with self.assertRaises(ValueError) as cm:
+            filestore._create_doc(good_id, 3)
+        self.assertEqual(
+            str(cm.exception),
+            'copies is 3, need 0 <= copies <= 2'
+        )
+
+        # Test with all possible good values for `copies`:
+        for copies in range(3):
+            store_id = random_id()
+            ts_before = time.time()
+            doc = filestore._create_doc(store_id, copies)
+            ts_after = time.time()
+            self.assertIsInstance(doc, dict)
+            ts = doc['time']
+            self.assertIsInstance(ts, float)
+            self.assertTrue(ts_before <= ts <= ts_after)
+            self.assertEqual(doc, {
+                '_id': store_id,
+                'time': ts,
+                'type': 'dmedia/store',
+                'plugin': 'filestore',
+                'copies': copies,
+            })
+
+        # Test with extra kwargs:
+        for copies in range(3):
+            store_id = random_id()
+            uuid = str(uuid4())
+            label = 'Dmedia' + random_id(5).lower()
+            kw = {'uuid': uuid, 'label': label}
+            ts_before = time.time()
+            doc = filestore._create_doc(store_id, copies, **kw)
+            ts_after = time.time()
+            self.assertIsInstance(doc, dict)
+            ts = doc['time']
+            self.assertIsInstance(ts, float)
+            self.assertTrue(ts_before <= ts <= ts_after)
+            self.assertEqual(doc, {
+                '_id': store_id,
+                'time': ts,
+                'type': 'dmedia/store',
+                'plugin': 'filestore',
+                'copies': copies,
+                'uuid': uuid,
+                'label': label,
+            })
+
+    def test_check_doc(self):
+        _id = random_id()
+        doc = {'_id': _id, 'copies': 1, 'type': 'dmedia/store'}
+        self.assertIs(filestore.check_doc(doc), doc)
+        self.assertEqual(
+            filestore.check_doc(doc),
+            {'_id': _id, 'copies': 1, 'type': 'dmedia/store'}
+        )
+
+        # expected_id is provided and doesn't match doc['_id']:
+        expected_id = random_id()
+        with self.assertRaises(ValueError) as cm:
+            filestore.check_doc(doc, expected_id=expected_id)
+        self.assertEqual(
+            str(cm.exception),
+            "doc['_id']: expected {!r}; got {!r}".format(expected_id, _id)
+        )
+
+        # Bad doc type:
+        doc_s = json.dumps(doc)
+        with self.assertRaises(TypeError) as cm:
+            filestore.check_doc(doc_s)
+        self.assertEqual(
+            str(cm.exception),
+            TYPE_ERROR.format('doc', dict, str, doc_s)
+        )
+
+        # Bad doc['_id'] type:
+        bad_id = _id.encode('utf-8')
+        bad = {'_id': bad_id, 'copies': 1, 'type': 'dmedia/store'}
+        with self.assertRaises(TypeError) as cm:
+            filestore.check_doc(bad)
+        self.assertEqual(
+            str(cm.exception),
+            TYPE_ERROR.format("doc['_id']", str, bytes, bad_id)
+        )
+
+        # Bad doc['_id'] value:
+        bad_id = random_id(10)
+        bad = {'_id': bad_id, 'copies': 1, 'type': 'dmedia/store'}
+        with self.assertRaises(ValueError) as cm:
+            filestore.check_doc(bad)
+        self.assertEqual(
+            str(cm.exception),
+            "len(doc['_id']) is 16, need 24: {!r}".format(bad_id)
+        )
+        bad_id = 'Z' * 24
+        bad = {'_id': bad_id, 'copies': 1, 'type': 'dmedia/store'}
+        with self.assertRaises(ValueError) as cm:
+            filestore.check_doc(bad)
+        self.assertEqual(
+            str(cm.exception),
+            "doc['_id'] is not a valid Dbase32 ID: {!r}".format(bad_id)
+        )
+
+        # Bad doc['copies'] type:
+        bad = {'_id': _id, 'copies': 1.5, 'type': 'dmedia/store'}
+        with self.assertRaises(TypeError) as cm:
+            filestore.check_doc(bad)
+        self.assertEqual(
+            str(cm.exception),
+            TYPE_ERROR.format("doc['copies']", int, float, 1.5)
+        )
+
+        # Bad doc['copies'] value:
+        bad = {'_id': _id, 'copies': -1, 'type': 'dmedia/store'}
+        with self.assertRaises(ValueError) as cm:
+            filestore.check_doc(bad)
+        self.assertEqual(
+            str(cm.exception),
+            "doc['copies'] is -1, need 0 <= doc['copies'] <= 2"
+        )
+        bad = {'_id': _id, 'copies': 3, 'type': 'dmedia/store'}
+        with self.assertRaises(ValueError) as cm:
+            filestore.check_doc(bad)
+        self.assertEqual(
+            str(cm.exception),
+            "doc['copies'] is 3, need 0 <= doc['copies'] <= 2"
+        )
+
+        # Bad doc['type'] value:
+        bad = {'_id': _id, 'copies': 1, 'type': 'dmedia/file'}
+        with self.assertRaises(ValueError) as cm:
+            filestore.check_doc(bad)
+        self.assertEqual(
+            str(cm.exception),
+            "doc['type'] is 'dmedia/file', must be 'dmedia/store'"
+        )
+
+    def test_check_parentdir(self):
+        tmp = TempDir()
+
+        # Test with relative path:
+        with self.assertRaises(filestore.PathError) as cm:
+            filestore._check_parentdir('foo/bar')
+        self.assertEqual(cm.exception.untrusted, 'foo/bar')
+        self.assertEqual(cm.exception.abspath, path.abspath('foo/bar'))
+        self.assertEqual(
+            str(cm.exception),
+            '{!r} resolves to {!r}'.format('foo/bar', path.abspath('foo/bar'))
+        )
+
+        # Test with path traversal:
+        with self.assertRaises(filestore.PathError) as cm:
+            filestore._check_parentdir('/foo/bar/../../root')
+        self.assertEqual(cm.exception.untrusted, '/foo/bar/../../root')
+        self.assertEqual(cm.exception.abspath, '/root')
+        self.assertEqual(
+            str(cm.exception),
+            '{!r} resolves to {!r}'.format('/foo/bar/../../root', '/root')
+        )
+
+        # Nested parentdir:
+        tmp.mkdir('.dmedia')
+        parentdir = tmp.mkdir('.dmedia', random_id().lower())
+        with self.assertRaises(filestore.NestedParent) as cm:
+            filestore._check_parentdir(parentdir)
+        self.assertEqual(cm.exception.parentdir, parentdir)
+        self.assertEqual(cm.exception.dotname, '.dmedia')
+
+        # parentdir does not exist:
+        parentdir = tmp.join(random_id().lower())
+        with self.assertRaises(ValueError) as cm:
+            filestore._check_parentdir(parentdir)
+        self.assertEqual(str(cm.exception),
+            'parentdir not a directory: {!r}'.format(parentdir)
+        )
+
+        # parentdir is a file:
+        parentdir = tmp.touch(random_id().lower())
+        with self.assertRaises(ValueError) as cm:
+            filestore._check_parentdir(parentdir)
+        self.assertEqual(str(cm.exception),
+            'parentdir not a directory: {!r}'.format(parentdir)
+        )
+
+        # When parentdir is good
+        parentdir = tmp.mkdir(random_id().lower())
+        self.assertEqual(filestore._check_parentdir(parentdir), parentdir)
+
+    def check_directory(self, fullname):
+        self.assertEqual(path.abspath(fullname), fullname)
+        st = os.stat(fullname, follow_symlinks=False)
+        self.assertTrue(stat.S_ISDIR(st.st_mode), fullname)
+        self.assertEqual(stat.S_IMODE(st.st_mode), 0o777, fullname)
+
+    def check_file(self, fullname, text):
+        self.assertEqual(path.abspath(fullname), fullname)
+        st = os.stat(fullname, follow_symlinks=False)
+        self.assertTrue(stat.S_ISREG(st.st_mode), fullname)
+        self.assertEqual(stat.S_IMODE(st.st_mode), 0o444, fullname)
+        self.assertEqual(open(fullname, 'r').read(), text)
+
+    def test_create_filestore(self):
+        tmp = TempDir()
+        store_id = random_id()
+
+        doc = filestore._create_filestore(tmp.dir, store_id, 1)
+        self.assertIsInstance(doc, dict)
+        ts = doc['time']
+        self.assertIsInstance(ts, float)
+        self.assertEqual(doc, {
+            '_id': store_id,
+            'time': ts,
+            'type': 'dmedia/store',
+            'plugin': 'filestore',
+            'copies': 1,
+        })
+
+        # Check the directories:
+        self.check_directory(tmp.join('.dmedia'))
+        for name in ('files', 'tmp', 'partial', 'corrupt'):
+            self.check_directory(tmp.join('.dmedia', name))
+        for name in filestore.DB32NAMES:
+            self.check_directory(tmp.join('.dmedia', 'files', name))
+
+        # Check the files:
+        self.check_file(tmp.join('.dmedia', 'README.txt'), filestore.README)
+        self.check_file(tmp.join('.dmedia', 'filestore.json'), filestore._dumps(doc))
+
+        # Check the directory contents:
+        self.assertEqual(os.listdir(tmp.dir), ['.dmedia'])
+        self.assertEqual(
+            sorted(os.listdir(tmp.join('.dmedia'))),
+            ['README.txt', 'corrupt', 'files', 'filestore.json', 'partial', 'tmp']
+        )
+        for name in ('tmp', 'partial', 'corrupt'):
+            self.assertEqual(os.listdir(tmp.join('.dmedia', name)), [])
+        self.assertEqual(
+            sorted(os.listdir(tmp.join('.dmedia', 'files'))),
+            list(filestore.DB32NAMES)
+        )
+        for name in filestore.DB32NAMES:
+            self.assertEqual(os.listdir(tmp.join('.dmedia', 'files', name)), [])
+
+        # Test when .dmedia already exists in parentdir:
         with self.assertRaises(OSError) as cm:
-            f(d)
-        self.assertEqual(
-            str(cm.exception), 
-            '[Errno 2] No such file or directory: {!r}'.format(d)
-        )
-        self.assertFalse(path.exists(d))
-        self.assertFalse(path.exists(tmp.join('foo')))
-
-        # Test when dir does not exist
-        d = tmp.join('foo')
-        self.assertFalse(path.exists(d))
-        self.assertIs(f(d), True)
-        self.assertTrue(path.isdir(d))
-
-        # Test when dir exists:
-        self.assertIs(f(d), False)
-        self.assertTrue(path.isdir(d))
-
-        # Test when dir exists and is a file:
-        d = tmp.touch('bar')
-        with self.assertRaises(ValueError) as cm:
-            f(d)
-        self.assertEqual(str(cm.exception), 'not a directory: {!r}'.format(d))
-
-        # Test when dir exists and is a symlink to a dir:
-        target = tmp.makedirs('target')
-        link = tmp.join('link')
-        os.symlink(target, link)
-        self.assertTrue(path.isdir(link))
-        self.assertTrue(path.islink(link))
-        with self.assertRaises(ValueError) as cm:
-            f(link)
-        self.assertEqual(
-            str(cm.exception),
-            '{!r} is symlink to {!r}'.format(link, target)
-        )
+            filestore._create_filestore(tmp.dir, store_id, 1)
+        self.assertEqual(str(cm.exception),
+            "[Errno 39] Directory not empty: '.dmedia'"
+        )
+        tmpname = '.dmedia-' + store_id
+        self.assertEqual(set(os.listdir(tmp.dir)), set(['.dmedia', tmpname]))
+        self.assertTrue(path.isfile(tmp.join(tmpname, 'filestore.json')))
+
+    def test_check_dir(self):
+        tmp = TempDir()
+        fs = filestore.FileStore.create(tmp.dir)
+        tmp.mkdir('.dmedia', 'foo')
+
+        # Test with a few good directories:
+        tmp.mkdir('.dmedia', 'good')
+        tmp.chmod(0o777, '.dmedia', 'good')
+        self.assertIsNone(fs._check_dir('good'))
+        tmp.mkdir('.dmedia', 'foo', 'good')
+        tmp.chmod(0o777, '.dmedia', 'foo', 'good')
+        self.assertIsNone(fs._check_dir('foo/good'))
+
+        # Test with symlinks to the same good directories:
+        self.assertTrue(path.isdir(tmp.symlink('good', '.dmedia', 'link')))
+        with self.assertRaises(ValueError) as cm:
+            fs._check_dir('link')
+        self.assertEqual(str(cm.exception),
+            "'link' not a directory in {!r}".format(fs.basedir)
+        )
+        self.assertTrue(path.isdir(tmp.symlink('good', '.dmedia', 'foo', 'link')))
+        with self.assertRaises(ValueError) as cm:
+            fs._check_dir('foo/link')
+        self.assertEqual(str(cm.exception),
+            "'foo/link' not a directory in {!r}".format(fs.basedir)
+        )
+
+        # Does not exist:
+        with self.assertRaises(FileNotFoundError) as cm:
+            fs._check_dir('nope')
+        self.assertEqual(cm.exception.filename, 'nope')
+        with self.assertRaises(FileNotFoundError) as cm:
+            fs._check_dir('foo/nope')
+        self.assertEqual(cm.exception.filename, 'foo/nope')
+
+        # A file instead of a directory:
+        tmp.touch('.dmedia', 'afile')
+        with self.assertRaises(ValueError) as cm:
+            fs._check_dir('afile')
+        self.assertEqual(str(cm.exception),
+            "'afile' not a directory in {!r}".format(fs.basedir)
+        )
+        tmp.touch('.dmedia', 'foo', 'afile')
+        with self.assertRaises(ValueError) as cm:
+            fs._check_dir('foo/afile')
+        self.assertEqual(str(cm.exception),
+            "'foo/afile' not a directory in {!r}".format(fs.basedir)
+        )
+
+        # Directory, but mode is not 0777:
+        tmp.mkdir('.dmedia', 'adir')
+        with self.assertRaises(ValueError) as cm:
+            fs._check_dir('adir')
+        self.assertEqual(str(cm.exception),
+            "Directory 'adir' mode not 0777 in {!r}".format(fs.basedir)
+        )
+        tmp.mkdir('.dmedia', 'foo', 'adir')
+        with self.assertRaises(ValueError) as cm:
+            fs._check_dir('foo/adir')
+        self.assertEqual(str(cm.exception),
+            "Directory 'foo/adir' mode not 0777 in {!r}".format(fs.basedir)
+        )
+
+        # All good:
+        tmp.chmod(0o777, '.dmedia', 'adir')
+        self.assertIsNone(fs._check_dir('adir'))
+        tmp.chmod(0o777, '.dmedia', 'foo', 'adir')
+        self.assertIsNone(fs._check_dir('foo/adir'))
+
+    def test_check_file(self):
+        tmp = TempDir()
+        fs = filestore.FileStore.create(tmp.dir)
+        tmp.mkdir('.dmedia', 'foo')
+
+        # Test with a few good files:
+        tmp.touch('.dmedia', 'good')
+        tmp.chmod(0o444, '.dmedia', 'good')
+        self.assertIsNone(fs._check_file('good'))
+        tmp.touch('.dmedia', 'foo', 'good')
+        tmp.chmod(0o444, '.dmedia', 'foo', 'good')
+        self.assertIsNone(fs._check_file('foo/good'))
+
+        # Test with symlinks to the same good files:
+        self.assertTrue(path.isfile(tmp.symlink('good', '.dmedia', 'link')))
+        with self.assertRaises(ValueError) as cm:
+            fs._check_file('link')
+        self.assertEqual(str(cm.exception),
+            "'link' not a file in {!r}".format(fs.basedir)
+        )
+        self.assertTrue(path.isfile(tmp.symlink('good', '.dmedia', 'foo', 'link')))
+        with self.assertRaises(ValueError) as cm:
+            fs._check_file('foo/link')
+        self.assertEqual(str(cm.exception),
+            "'foo/link' not a file in {!r}".format(fs.basedir)
+        )
+
+        # File does not exist:
+        with self.assertRaises(FileNotFoundError) as cm:
+            fs._check_file('nope')
+        self.assertEqual(cm.exception.filename, 'nope')
+        with self.assertRaises(FileNotFoundError) as cm:
+            fs._check_file('foo/nope')
+        self.assertEqual(cm.exception.filename, 'foo/nope')
+
+        # Directory instead of a file:
+        tmp.mkdir('.dmedia', 'adir')
+        with self.assertRaises(ValueError) as cm:
+            fs._check_file('adir')
+        self.assertEqual(str(cm.exception),
+            "'adir' not a file in {!r}".format(fs.basedir)
+        )
+        tmp.mkdir('.dmedia', 'foo', 'adir')
+        with self.assertRaises(ValueError) as cm:
+            fs._check_file('foo/adir')
+        self.assertEqual(str(cm.exception),
+            "'foo/adir' not a file in {!r}".format(fs.basedir)
+        )
+
+        # File, but mode is not 0444:
+        tmp.touch('.dmedia', 'afile')
+        with self.assertRaises(ValueError) as cm:
+            fs._check_file('afile')
+        self.assertEqual(str(cm.exception),
+            "File 'afile' mode not 0444 in {!r}".format(fs.basedir)
+        )
+        tmp.touch('.dmedia', 'foo', 'afile')
+        with self.assertRaises(ValueError) as cm:
+            fs._check_file('foo/afile')
+        self.assertEqual(str(cm.exception),
+            "File 'foo/afile' mode not 0444 in {!r}".format(fs.basedir)
+        )
+
+        # All good:
+        tmp.chmod(0o444, '.dmedia', 'afile')
+        self.assertIsNone(fs._check_file('afile'))
+        tmp.chmod(0o444, '.dmedia', 'foo', 'afile')
+        self.assertIsNone(fs._check_file('foo/afile'))
+
+    def test_check_layout(self):
+        # FIXME: also needs to test that symlinks aren't followed!
+        tmp = TempDir()
+        fs = filestore.FileStore.create(tmp.dir)
+
+        # Cause some damage:
+        tmp.chmod(0o750, '.dmedia', 'files')
+        tmp.rmdir('.dmedia', 'tmp')
+        tmp.touch('.dmedia', 'tmp')
+        tmp.rmdir('.dmedia', 'corrupt')
+        tmp.chmod(0o750, '.dmedia', 'files', '39')
+        tmp.rmdir('.dmedia', 'files', '69')
+        tmp.touch('.dmedia', 'files', '69')
+        tmp.rmdir('.dmedia', 'files', 'AY')
+        tmp.chmod(0o600, '.dmedia', 'README.txt')
+        tmp.touch('.dmedia', 'good-file')
+        tmp.chmod(0o444, '.dmedia', 'good-file')
+        tmp.remove('.dmedia', 'filestore.json')
+        self.assertTrue(path.isfile(tmp.symlink('good-file', '.dmedia', 'filestore.json')))
+        self.assertIsNone(fs._check_file('good-file'))
+
+        # Test for expected execption, fix damage one by one:
+        # files/
+        with self.assertRaises(ValueError) as cm:
+            fs.check_layout()
+        self.assertEqual(str(cm.exception),
+            "Directory 'files' mode not 0777 in {!r}".format(fs.basedir)
+        )
+        tmp.chmod(0o777, '.dmedia', 'files')
+
+        # tmp/
+        with self.assertRaises(ValueError) as cm:
+            fs.check_layout()
+        self.assertEqual(str(cm.exception),
+            "'tmp' not a directory in {!r}".format(fs.basedir)
+        )
+        tmp.remove('.dmedia', 'tmp')
+        tmp.mkdir('.dmedia', 'tmp')
+        with self.assertRaises(ValueError) as cm:
+            fs.check_layout()
+        self.assertEqual(str(cm.exception),
+            "Directory 'tmp' mode not 0777 in {!r}".format(fs.basedir)
+        )
+        tmp.chmod(0o777, '.dmedia', 'tmp')
+
+        # corrupt/
+        with self.assertRaises(FileNotFoundError) as cm:
+            fs.check_layout()
+        self.assertEqual(cm.exception.filename, 'corrupt')
+        tmp.mkdir('.dmedia', 'corrupt')
+        with self.assertRaises(ValueError) as cm:
+            fs.check_layout()
+        self.assertEqual(str(cm.exception),
+            "Directory 'corrupt' mode not 0777 in {!r}".format(fs.basedir)
+        )
+        tmp.chmod(0o777, '.dmedia', 'corrupt')
+
+        # files/39/
+        with self.assertRaises(ValueError) as cm:
+            fs.check_layout()
+        self.assertEqual(str(cm.exception),
+            "Directory 'files/39' mode not 0777 in {!r}".format(fs.basedir)
+        )
+        tmp.chmod(0o777, '.dmedia', 'files', '39')
+
+        # files/69/
+        with self.assertRaises(ValueError) as cm:
+            fs.check_layout()
+        self.assertEqual(str(cm.exception),
+            "'files/69' not a directory in {!r}".format(fs.basedir)
+        )
+        tmp.remove('.dmedia', 'files', '69')
+        tmp.mkdir('.dmedia', 'files', '69')
+        with self.assertRaises(ValueError) as cm:
+            fs.check_layout()
+        self.assertEqual(str(cm.exception),
+            "Directory 'files/69' mode not 0777 in {!r}".format(fs.basedir)
+        )
+        tmp.chmod(0o777, '.dmedia', 'files', '69')
+
+        # files/AY/
+        with self.assertRaises(FileNotFoundError) as cm:
+            fs.check_layout()
+        self.assertEqual(cm.exception.filename, 'files/AY')
+        tmp.mkdir('.dmedia', 'files/AY')
+        with self.assertRaises(ValueError) as cm:
+            fs.check_layout()
+        self.assertEqual(str(cm.exception),
+            "Directory 'files/AY' mode not 0777 in {!r}".format(fs.basedir)
+        )
+        tmp.chmod(0o777, '.dmedia', 'files', 'AY')
+
+        # README.txt
+        with self.assertRaises(ValueError) as cm:
+            fs.check_layout()
+        self.assertEqual(str(cm.exception),
+            "File 'README.txt' mode not 0444 in {!r}".format(fs.basedir)
+        )
+        tmp.chmod(0o444, '.dmedia', 'README.txt')
+
+        # filestore.json
+        with self.assertRaises(ValueError) as cm:
+            fs.check_layout()
+        self.assertEqual(str(cm.exception),
+            "'filestore.json' not a file in {!r}".format(fs.basedir)
+        )
+        tmp.remove('.dmedia', 'filestore.json')
+        with self.assertRaises(FileNotFoundError) as cm:
+            fs.check_layout()
+        self.assertEqual(cm.exception.filename, 'filestore.json')
+        tmp.touch('.dmedia', 'filestore.json')
+        with self.assertRaises(ValueError) as cm:
+            fs.check_layout()
+        self.assertEqual(str(cm.exception),
+            "File 'filestore.json' mode not 0444 in {!r}".format(fs.basedir)
+        )
+        tmp.chmod(0o444, '.dmedia', 'filestore.json')
+
+        # All damage fixed:
+        self.assertIsNone(fs.check_layout())
+
+        # Test once more with a prestine layout:
+        tmp = TempDir()
+        fs = filestore.FileStore.create(tmp.dir)
+        self.assertIsNone(fs.check_layout())
+        del fs
+        fs = filestore.FileStore(tmp.dir)
+        self.assertIsNone(fs.check_layout())
 
     def test_statvfs(self):
         tmp = TempDir()
@@ -1287,90 +1796,6 @@
             filestore.StatVFS(size, size - free, avail, False, s1.f_frsize)
         )
 
-    def test_is_v0_files(self):
-        v0 = TempDir()
-        for name in filestore.B32NAMES:
-            v0.mkdir(name)
-        self.assertIs(filestore.is_v0_files(v0.dir), True)
-        v1 = TempDir()
-        for name in filestore.DB32NAMES:
-            v1.mkdir(name)
-        self.assertIs(filestore.is_v0_files(v1.dir), False)
-        tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
-        files = tmp.join('.dmedia', 'files')
-        self.assertTrue(path.isdir(files))
-        self.assertIs(filestore.is_v0_files(files), False)
-
-    def test_migrate_store_doc(self):
-        tmp = TempDir()
-        store = tmp.join('store.json')
-        store0 = tmp.join('store0.json')
-        self.assertIs(filestore.migrate_store_doc(tmp.dir), False)
-
-        # A V0 doc:
-        doc = {
-            '_id': 'DLA4NDZRW2LXEPF3RV7YHMON',
-            'copies': 1,
-            'plugin': 'filestore',
-            'time': 1320063400.353743,
-            'type': 'dmedia/store',
-        }
-        json.dump(doc, open(store, 'x'))
-        self.assertIs(filestore.migrate_store_doc(tmp.dir), True)
-        self.assertEqual(json.load(open(store, 'r')),
-            {
-                '_id': '6E3VG6SKPTEQ7I8UKOYRAFHG',
-                'copies': 1,
-                'plugin': 'filestore',
-                'time': 1320063400.353743,
-                'type': 'dmedia/store',
-                'migrated': True,
-            }
-        )
-        self.assertEqual(stat.S_IMODE(os.stat(store).st_mode), 0o444)
-        self.assertEqual(json.load(open(store0, 'r')), doc)
-        self.assertEqual(
-            set(os.listdir(tmp.dir)),
-            {'store.json', 'store0.json'}
-        )
-        with self.assertRaises(Exception) as cm:
-            filestore.migrate_store_doc(tmp.dir)
-        self.assertEqual(
-            str(cm.exception),
-            "'store0.json' already exists in {!r}".format(tmp.dir)
-        )
-
-        # Try with some random ID values:
-        for i in range(25):
-            tmp = TempDir()
-            store = tmp.join('store.json')
-            store0 = tmp.join('store0.json')
-            data = os.urandom(15)
-            b32_id = b32enc(data)
-            db32_id = db32enc(data)
-            self.assertNotEqual(b32_id, db32_id)
-            json.dump({'_id': b32_id}, open(store, 'x'))
-            self.assertIs(filestore.migrate_store_doc(tmp.dir), True)
-            self.assertEqual(json.load(open(store, 'r')),
-                {
-                    '_id': db32_id,
-                    'migrated': True,
-                }
-            )
-            self.assertEqual(stat.S_IMODE(os.stat(store).st_mode), 0o444)
-            self.assertEqual(json.load(open(store0, 'r')), {'_id': b32_id})
-            self.assertEqual(
-                set(os.listdir(tmp.dir)),
-                {'store.json', 'store0.json'}
-            )
-            with self.assertRaises(Exception) as cm:
-                filestore.migrate_store_doc(tmp.dir)
-            self.assertEqual(
-                str(cm.exception),
-                "'store0.json' already exists in {!r}".format(tmp.dir)
-            )
-
 
 class TestHasher(TestCase):
     def test_init(self):
@@ -1486,11 +1911,41 @@
 
 
 class TestFileStore(TestCase):
-    def test_init(self):
-
+    def check_subdirs(self, basedir):
+        self.assertEqual(
+            sorted(os.listdir(basedir)),
+            ['README.txt', 'corrupt', 'files', 'filestore.json', 'partial', 'tmp']
+        )
+
+        f = path.join(basedir, 'README.txt')
+        self.assertFalse(path.islink(f))
+        self.assertEqual(open(f, 'r').read(), filestore.README)
+
+        self.assertEqual(
+            sorted(os.listdir(path.join(basedir, 'files'))),
+            list(filestore.DB32NAMES)
+        )
+        for name in ['corrupt', 'partial', 'tmp']:
+            d = path.join(basedir, name)
+            self.assertEqual(os.listdir(d), [])
+
+        for name in ['corrupt', 'files', 'partial', 'tmp']:
+            d = path.join(basedir, name)
+            self.assertTrue(path.isdir(d))
+            self.assertFalse(path.islink(d))
+        for name in filestore.DB32NAMES:
+            d = path.join(basedir, 'files', name)
+            self.assertTrue(path.isdir(d))
+            self.assertFalse(path.islink(d))
+            self.assertEqual(os.listdir(d), [])
+
+    def test_create(self):
+        """
+        Test the FileStore.create() classmethod
+        """
         # Test with relative path:
         with self.assertRaises(filestore.PathError) as cm:
-            fs = filestore.FileStore('foo/bar')
+            fs = filestore.FileStore.create('foo/bar')
         self.assertEqual(cm.exception.untrusted, 'foo/bar')
         self.assertEqual(cm.exception.abspath, path.abspath('foo/bar'))
         self.assertEqual(
@@ -1500,7 +1955,7 @@
 
         # Test with path traversal:
         with self.assertRaises(filestore.PathError) as cm:
-            fs = filestore.FileStore('/foo/bar/../../root')
+            fs = filestore.FileStore.create('/foo/bar/../../root')
         self.assertEqual(cm.exception.untrusted, '/foo/bar/../../root')
         self.assertEqual(cm.exception.abspath, '/root')
         self.assertEqual(
@@ -1512,7 +1967,7 @@
         tmp = TempDir()
         parentdir = tmp.makedirs('.dmedia', 'foo')
         with self.assertRaises(filestore.NestedParent) as cm:
-            fs = filestore.FileStore(parentdir)
+            fs = filestore.FileStore.create(parentdir)
         self.assertEqual(cm.exception.parentdir, parentdir)
         self.assertEqual(cm.exception.dotname, '.dmedia')
         self.assertEqual(
@@ -1524,167 +1979,192 @@
         tmp = TempDir()
         parentdir = tmp.join('nope')
         with self.assertRaises(ValueError) as cm:
-            fs = filestore.FileStore(parentdir)
+            fs = filestore.FileStore.create(parentdir)
         self.assertEqual(
             str(cm.exception),
-            'FileStore.parentdir not a directory: {!r}'.format(parentdir)
+            'parentdir not a directory: {!r}'.format(parentdir)
         )
 
         # Test when parentdir is a file:
         tmp = TempDir()
         parentdir = tmp.touch('somefile')
         with self.assertRaises(ValueError) as cm:
-            fs = filestore.FileStore(parentdir)
+            fs = filestore.FileStore.create(parentdir)
         self.assertEqual(
             str(cm.exception),
-            'FileStore.parentdir not a directory: {!r}'.format(parentdir)
+            'parentdir not a directory: {!r}'.format(parentdir)
         )
 
-        # Test when basedir does not exist
+        # Test when basedir does not exist:
         tmp = TempDir()
         basedir = tmp.join('.dmedia')
         self.assertFalse(path.exists(basedir))
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         self.assertEqual(fs.parentdir, tmp.dir)
         self.assertEqual(fs.basedir, basedir)
         self.assertTrue(path.isdir(basedir))
         self.assertEqual(fs.tmp, path.join(basedir, 'tmp'))
         self.assertTrue(path.isdir(fs.tmp))
-        self.assertIsNone(fs.id)
-        self.assertEqual(fs.copies, 0)
-        self.assertFalse(fs.needs_migration)
+        self.assertIsInstance(fs.id, str)
+        self.assertEqual(len(fs.id), 24)
+        self.assertTrue(isdb32(fs.id))
+        self.assertEqual(fs.copies, 1)
+        self.check_subdirs(fs.basedir)
 
         # Test when _id and copies are supplied
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir, 'foo', 1)
-        self.assertEqual(fs.id, 'foo')
-        self.assertEqual(fs.copies, 1)
-        self.assertFalse(fs.needs_migration)
+        store_id = random_id()
+        fs = filestore.FileStore.create(tmp.dir, store_id, 2)
+        self.assertEqual(fs.id, store_id)
+        self.assertEqual(fs.copies, 2)
+        self.check_subdirs(fs.basedir)
 
         # Test when basedir exists and is a directory
         tmp = TempDir()
-        basedir = tmp.makedirs('.dmedia')
-        fs = filestore.FileStore(tmp.dir)
-        self.assertEqual(fs.parentdir, tmp.dir)
-        self.assertEqual(fs.basedir, basedir)
-        self.assertTrue(path.isdir(basedir))
-        self.assertEqual(fs.tmp, path.join(basedir, 'tmp'))
-        self.assertFalse(path.isdir(fs.tmp))
-        self.assertFalse(fs.needs_migration)
+        basedir = tmp.mkdir('.dmedia')
+        with self.assertRaises(ValueError) as cm:
+            filestore.FileStore.create(tmp.dir)
+        self.assertEqual(str(cm.exception),
+            'Cannot create FileStore, dotdir exists: {!r}'.format(basedir)
+        )
 
         # Test when basedir exists and is a file
         tmp = TempDir()
         basedir = tmp.touch('.dmedia')
         with self.assertRaises(ValueError) as cm:
-            fs = filestore.FileStore(tmp.dir)
-        self.assertEqual(
-            str(cm.exception),
-            'not a directory: {!r}'.format(basedir)
-        )
-
-        # Test when basedir exists and is a symlink to a dir
-        tmp = TempDir()
-        d = tmp.makedirs('foo')
-        basedir = tmp.join('.dmedia')
-        os.symlink(d, basedir)
-        with self.assertRaises(ValueError) as cm:
-            fs = filestore.FileStore(tmp.dir)
-        self.assertEqual(
-            str(cm.exception),
-            '{!r} is symlink to {!r}'.format(basedir, d)
-        )
-
-        # Test when .dmedia/files/ contains a V0, Base32 layout:
-        tmp = TempDir()
-        files = tmp.join('.dmedia', 'files')
-        files0 = tmp.join('.dmedia', 'files0')
-        fs = filestore.FileStore(tmp.dir)
-        shutil.rmtree(files)
-        os.mkdir(files)
-        for name in filestore.B32NAMES:
-            os.mkdir(path.join(files, name))
-        fs = filestore.FileStore(tmp.dir)
-        self.assertTrue(fs.needs_migration)
-        self.assertTrue(path.isdir(files))
-        for name in filestore.DB32NAMES:
-            self.assertTrue(path.isdir(path.join(files, name)))
-        self.assertEqual(sorted(os.listdir(files)), list(filestore.DB32NAMES))
-        self.assertTrue(path.isdir(files0))
-        for name in filestore.B32NAMES:
-            self.assertTrue(path.isdir(path.join(files0, name)))
-        self.assertEqual(sorted(os.listdir(files0)), list(filestore.B32NAMES))
-
-        # Test that no futher change is done:
-        fs = filestore.FileStore(tmp.dir)
-        self.assertTrue(fs.needs_migration)
-        self.assertTrue(path.isdir(files))
-        for name in filestore.DB32NAMES:
-            self.assertTrue(path.isdir(path.join(files, name)))
-        self.assertEqual(sorted(os.listdir(files)), list(filestore.DB32NAMES))
-        self.assertTrue(path.isdir(files0))
-        for name in filestore.B32NAMES:
-            self.assertTrue(path.isdir(path.join(files0, name)))
-        self.assertEqual(sorted(os.listdir(files0)), list(filestore.B32NAMES))
-
-        # Test when files contains V0/Base32 layout but files0 already exists:
-        shutil.rmtree(files)
-        os.mkdir(files)
-        for name in filestore.B32NAMES:
-            os.mkdir(path.join(files, name))
-        with self.assertRaises(Exception) as cm:
-            fs = filestore.FileStore(tmp.dir)
-        self.assertEqual(
-            str(cm.exception),
-            "'files' is V0 layout but 'files0' exists in {!r}".format(tmp.join('.dmedia'))   
-        )
-
-        # Test that store.json gets properly migrated:
-        tmp = TempDir()
-        files = tmp.join('.dmedia', 'files')
-        files0 = tmp.join('.dmedia', 'files0')
-        store = tmp.join('.dmedia', 'store.json')
-        store0 = tmp.join('.dmedia', 'store0.json')
-
-        # Setup:
-        fs = filestore.FileStore(tmp.dir)
-        shutil.rmtree(files)
-        os.mkdir(files)
-        for name in filestore.B32NAMES:
-            os.mkdir(path.join(files, name))
-        data = os.urandom(15)
-        b32_id = b32enc(data)
-        db32_id = db32enc(data)
-        self.assertNotEqual(b32_id, db32_id)
-        json.dump({'_id': b32_id}, open(store, 'x'))
-
-        # And test:
-        fs = filestore.FileStore(tmp.dir)
-        self.assertTrue(fs.needs_migration)
-        self.assertTrue(path.isdir(files))
-        for name in filestore.DB32NAMES:
-            self.assertTrue(path.isdir(path.join(files, name)))
-        self.assertEqual(sorted(os.listdir(files)), list(filestore.DB32NAMES))
-        self.assertTrue(path.isdir(files0))
-        for name in filestore.B32NAMES:
-            self.assertTrue(path.isdir(path.join(files0, name)))
-        self.assertEqual(sorted(os.listdir(files0)), list(filestore.B32NAMES))
-        self.assertEqual(json.load(open(store, 'r')),
-            {
-                '_id': db32_id,
-                'migrated': True,
-            }
-        )
-        self.assertEqual(stat.S_IMODE(os.stat(store).st_mode), 0o444)
-        self.assertEqual(json.load(open(store0, 'r')), {'_id': b32_id})
+            filestore.FileStore.create(tmp.dir)
+        self.assertEqual(str(cm.exception),
+            'Cannot create FileStore, dotdir exists: {!r}'.format(basedir)
+        )
+
+    def test_init(self):
+        # Test with relative path:
+        with self.assertRaises(filestore.PathError) as cm:
+            fs = filestore.FileStore('foo/bar')
+        self.assertEqual(cm.exception.untrusted, 'foo/bar')
+        self.assertEqual(cm.exception.abspath, path.abspath('foo/bar'))
+        self.assertEqual(
+            str(cm.exception),
+            '{!r} resolves to {!r}'.format('foo/bar', path.abspath('foo/bar'))
+        )
+
+        # Test with path traversal:
+        with self.assertRaises(filestore.PathError) as cm:
+            fs = filestore.FileStore('/foo/bar/../../root')
+        self.assertEqual(cm.exception.untrusted, '/foo/bar/../../root')
+        self.assertEqual(cm.exception.abspath, '/root')
+        self.assertEqual(
+            str(cm.exception),
+            '{!r} resolves to {!r}'.format('/foo/bar/../../root', '/root')
+        )
+
+        # Test with a nested parentdir:
+        tmp = TempDir()
+        parentdir = tmp.makedirs('.dmedia', 'foo')
+        with self.assertRaises(filestore.NestedParent) as cm:
+            fs = filestore.FileStore(parentdir)
+        self.assertEqual(cm.exception.parentdir, parentdir)
+        self.assertEqual(cm.exception.dotname, '.dmedia')
+        self.assertEqual(
+            str(cm.exception),
+            '{!r} contains {!r}'.format(parentdir, '.dmedia')
+        )
+
+        # Test when parentdir doesn't exists:
+        tmp = TempDir()
+        parentdir = tmp.join('nope')
+        with self.assertRaises(ValueError) as cm:
+            fs = filestore.FileStore(parentdir)
+        self.assertEqual(
+            str(cm.exception),
+            'parentdir not a directory: {!r}'.format(parentdir)
+        )
+
+        # Test when parentdir is a file:
+        tmp = TempDir()
+        parentdir = tmp.touch('somefile')
+        with self.assertRaises(ValueError) as cm:
+            fs = filestore.FileStore(parentdir)
+        self.assertEqual(
+            str(cm.exception),
+            'parentdir not a directory: {!r}'.format(parentdir)
+        )
+
+        # Test when FileStore has not been initialized with FileStore.create():
+        tmp = TempDir()
+        with self.assertRaises(FileNotFoundError) as cm:
+            filestore.FileStore(tmp.dir)
+
+        # Test when basedir exists and is a file
+        tmp = TempDir()
+        tmp.touch('.dmedia')
+        with self.assertRaises(NotADirectoryError) as cm:
+            filestore.FileStore(tmp.dir)
+
+        # Test when FileStore was properly initalized:
+        tmp = TempDir()
+        store_id = random_id()
+        doc = filestore._create_filestore(tmp.dir, store_id, 1)
+        fs = filestore.FileStore(tmp.dir)
+        self.assertEqual(fs.parentdir, tmp.dir)
+        self.assertEqual(fs.basedir, tmp.join('.dmedia'))
+        self.assertIsInstance(fs.dir_fd, int)
+        self.assertEqual(fs.doc, doc)
+        self.assertEqual(fs.id, store_id)
+        self.assertEqual(fs.copies, 1)
+        self.assertEqual(fs.tmp, tmp.join('.dmedia', 'tmp'))
+        self.check_subdirs(fs.basedir)
+
+        # Test when expected_id is provided and matches:
+        fs = filestore.FileStore(tmp.dir, expected_id=store_id)
+        self.assertEqual(fs.parentdir, tmp.dir)
+        self.assertEqual(fs.basedir, tmp.join('.dmedia'))
+        self.assertIsInstance(fs.dir_fd, int)
+        self.assertEqual(fs.doc, doc)
+        self.assertEqual(fs.id, store_id)
+        self.assertEqual(fs.copies, 1)
+        self.assertEqual(fs.tmp, tmp.join('.dmedia', 'tmp'))
+        self.check_subdirs(fs.basedir)
+
+        # Test when expected_id is provided and does *not* match:
+        wrong_id = random_id()
+        with self.assertRaises(ValueError) as cm:
+            filestore.FileStore(tmp.dir, expected_id=wrong_id)
+        self.assertEqual(str(cm.exception),
+            "doc['_id']: expected {!r}; got {!r}".format(wrong_id, store_id)
+        )
 
     def test_repr(self):
-        tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
-        self.assertEqual(repr(fs), 'FileStore({!r})'.format(tmp.dir))
+        # With auto-generated ID:
+        tmp = TempDir()
+        fs = filestore.FileStore.create(tmp.dir)
+        store_id = fs.id
+        self.assertTrue(isdb32(store_id) and len(store_id) == 24)
+        self.assertEqual(repr(fs),
+            'FileStore({!r}, {!r})'.format(tmp.dir, store_id)
+        )
+        del fs
+        fs = filestore.FileStore(tmp.dir)
+        self.assertEqual(repr(fs),
+            'FileStore({!r}, {!r})'.format(tmp.dir, store_id)
+        )
+
+        # With explicit ID:
+        tmp = TempDir()
+        store_id = random_id()
+        fs = filestore.FileStore.create(tmp.dir, store_id)
+        self.assertEqual(repr(fs),
+            'FileStore({!r}, {!r})'.format(tmp.dir, store_id)
+        )
+        del fs
+        fs = filestore.FileStore(tmp.dir)
+        self.assertEqual(repr(fs),
+            'FileStore({!r}, {!r})'.format(tmp.dir, store_id)
+        )
 
     def test_iter(self):
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
 
         # Should ignore files with wrong ID length:
         short = tuple(random_file_id(25) for i in range(50))
@@ -1766,61 +2246,9 @@
             assert path.islink(fs.path(_id))
         self.assertEqual(list(fs), stats)
 
-    def check_subdirs(self, basedir):
-        self.assertEqual(
-            sorted(os.listdir(basedir)),
-            ['README.txt', 'corrupt', 'files', 'partial', 'tmp']
-        )
-
-        f = path.join(basedir, 'README.txt')
-        self.assertFalse(path.islink(f))
-        self.assertEqual(open(f, 'rt').read(), filestore.README)
-
-        self.assertEqual(
-            sorted(os.listdir(path.join(basedir, 'files'))),
-            list(filestore.DB32NAMES)
-        )
-        for name in ['corrupt', 'partial', 'tmp']:
-            d = path.join(basedir, name)
-            self.assertEqual(os.listdir(d), [])
-
-        for name in ['corrupt', 'files', 'partial', 'tmp']:
-            d = path.join(basedir, name)
-            self.assertTrue(path.isdir(d))
-            self.assertFalse(path.islink(d))
-        for name in filestore.DB32NAMES:
-            d = path.join(basedir, 'files', name)
-            self.assertTrue(path.isdir(d))
-            self.assertFalse(path.islink(d))
-            self.assertEqual(os.listdir(d), [])
-
-    def test_init_dirs(self):
-        tmp = TempDir()
-
-        # Create basedir dir so init_dirs() doesn't get called
-        basedir = tmp.makedirs('.dmedia')
-        fs = filestore.FileStore(tmp.dir)
-        self.assertEqual(os.listdir(basedir), [])
-
-        # Test when no subdirs exist:
-        self.assertIsNone(fs.init_dirs())
-        self.check_subdirs(basedir)
-
-        # Test when all subdirs exist:
-        self.assertIsNone(fs.init_dirs())
-        self.check_subdirs(basedir)
-
-        # Test when some subdirs exist:
-        os.rmdir(path.join(basedir, 'tmp'))
-        for (i, name) in enumerate(filestore.DB32NAMES):
-            if i % 3 == 0:
-                d = path.join(basedir, 'files', name)
-        self.assertIsNone(fs.init_dirs())
-        self.check_subdirs(basedir)
-
     def test_statvfs(self):
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         s1 = os.statvfs(tmp.dir)
         s2 = fs.statvfs()
         self.assertIsInstance(s2, filestore.StatVFS)
@@ -1835,7 +2263,7 @@
         tmp = TempDir()
         parentdir = tmp.makedirs('foo')
         basedir = tmp.join('foo', '.dmedia')
-        fs = filestore.FileStore(parentdir)
+        fs = filestore.FileStore.create(parentdir)
 
         bad = tmp.join('foo', '.dmedia2', 'stuff')
         with self.assertRaises(filestore.PathTraversal) as cm:
@@ -1858,7 +2286,7 @@
     def test_join(self):
         tmp = TempDir()
         parentdir = tmp.makedirs('foo')
-        fs = filestore.FileStore(parentdir)
+        fs = filestore.FileStore.create(parentdir)
 
         # Test with an absolute path in parts:
         with self.assertRaises(filestore.PathTraversal) as cm:
@@ -1900,7 +2328,7 @@
     def test_path(self):
         tmp = TempDir()
         parentdir = tmp.makedirs('foo')
-        fs = filestore.FileStore(parentdir)
+        fs = filestore.FileStore.create(parentdir)
 
         _id = random_file_id()
         self.assertEqual(
@@ -1917,7 +2345,7 @@
     def test_partial_path(self):
         tmp = TempDir()
         parentdir = tmp.makedirs('foo')
-        fs = filestore.FileStore(parentdir)
+        fs = filestore.FileStore.create(parentdir)
 
         _id = random_file_id()
         self.assertEqual(
@@ -1934,7 +2362,7 @@
     def test_corrupt_path(self):
         tmp = TempDir()
         parentdir = tmp.makedirs('foo')
-        fs = filestore.FileStore(parentdir)
+        fs = filestore.FileStore.create(parentdir)
 
         _id = random_file_id()
         self.assertEqual(
@@ -1950,7 +2378,7 @@
 
     def test_random_tmp_path(self):
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         filename = fs.random_tmp_path()
         self.assertEqual(path.dirname(filename), fs.tmp)
         name = path.basename(filename)
@@ -1960,7 +2388,7 @@
 
     def test_exists(self):
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
 
         id1 = random_file_id()
 
@@ -1988,7 +2416,7 @@
     def test_stat(self):
         # File doesn't exist
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         _id = random_file_id()
         with self.assertRaises(filestore.FileNotFound) as cm:
             st = fs.stat(_id)
@@ -2001,7 +2429,7 @@
 
         # File is a symlink:
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         file = random_file_id()
         link = random_file_id()
         open(fs.path(file), 'xb').write(b'Novacut')
@@ -2019,7 +2447,7 @@
 
         # File is a directory
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         _id = random_file_id()
         os.mkdir(fs.path(_id))
         assert path.isdir(fs.path(_id))
@@ -2034,7 +2462,7 @@
 
         # Empty file
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         _id = random_file_id()
         open(fs.path(_id), 'wb').close()
         assert path.isfile(fs.path(_id))
@@ -2051,7 +2479,7 @@
 
         # Valid file
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         _id = random_file_id()
         open(fs.path(_id), 'wb').write(b'Novacut')
         st = fs.stat(_id)
@@ -2063,7 +2491,7 @@
 
     def test_open(self):
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
 
         _id = random_file_id()
 
@@ -2086,7 +2514,7 @@
 
     def test_verify(self):
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
 
         canonical = fs.path(ID)
         corrupt = fs.corrupt_path(ID)
@@ -2134,7 +2562,7 @@
 
     def test_verify_iter(self):
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         canonical = fs.path(ID)
         corrupt = fs.corrupt_path(ID)
 
@@ -2230,7 +2658,7 @@
 
     def test_verify_iter2(self):
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
 
         canonical = fs.path(ID)
         corrupt = fs.corrupt_path(ID)
@@ -2277,7 +2705,7 @@
 
     def test_content_md5(self):
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
 
         canonical = fs.path(ID)
         corrupt = fs.corrupt_path(ID)
@@ -2322,7 +2750,7 @@
 
     def test_remove(self):
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         _id = random_file_id()
         canonical = fs.path(_id)
 
@@ -2340,7 +2768,7 @@
     def test_purge_tmp(self):
         tmp = TempDir()
         t = tmp.join('.dmedia', 'tmp')
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         self.assertTrue(path.isdir(t))
 
         # Test when nothing is in tmp:
@@ -2373,7 +2801,7 @@
 
         # Test that symlinks are ignored:
         tmp2 = TempDir()
-        fs2 = filestore.FileStore(tmp2.dir)
+        fs2 = filestore.FileStore.create(tmp2.dir)
         names = ['aye', 'bee', 'see']
         for i in range(10):
             size = random.randint(1, 1024 * 1024)
@@ -2410,7 +2838,7 @@
     def test_allocate_tmp(self):
         tmp = TempDir()
         t = tmp.join('.dmedia', 'tmp')
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         self.assertTrue(path.isdir(t))
 
         # Test with size=None
@@ -2458,7 +2886,7 @@
 
     def test_allocate_partial(self):
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         _id = random_file_id()
         filename = tmp.join('.dmedia', 'partial', _id)
 
@@ -2530,7 +2958,7 @@
 
     def test_move_to_canonical(self):
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         _id = random_file_id()
         dst = fs.path(_id)
 
@@ -2601,7 +3029,7 @@
 
     def test_move_to_corrupt(self):
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         _id = random_file_id()
         corrupt = fs.corrupt_path(_id)
         canonical = fs.path(_id)
@@ -2685,7 +3113,7 @@
     def test_verify_and_move(self):
         # Test when it's all good
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         src = fs.partial_path(ID)
         write_sample_file(src)
         src_fp = open(src, 'rb')
@@ -2696,7 +3124,7 @@
 
         # Test when tmp_fp.name != partial_path(_id)
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         src = path.join(fs.tmp, 'foo.mov')
         write_sample_file(src)
         src_fp = open(src, 'rb')
@@ -2710,7 +3138,7 @@
 
         # Test when partial has wrong content
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         src = fs.partial_path(ID)
         src_fp = open(src, 'wb')
         for leaf in LEAVES:
@@ -2730,7 +3158,7 @@
 
     def test_hash_and_move(self):
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         src = path.join(fs.tmp, 'foo.mov')
         write_sample_file(src)
         src_fp = open(src, 'rb')
@@ -2741,7 +3169,7 @@
 
         # Test David's use case:
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         tmp_fp = fs.allocate_tmp()
         write_sample_file(tmp_fp)
         self.assertFalse(fs.exists(ID))
@@ -2754,7 +3182,7 @@
         src = tmp.join('movie.mov')
         write_sample_file(src)
 
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
         dst = fs.path(ID)
         self.assertTrue(path.isfile(src))
         self.assertFalse(path.exists(dst))
@@ -2768,12 +3196,12 @@
 
     def test_copy(self):
         tmp = TempDir()
-        fs = filestore.FileStore(tmp.dir)
+        fs = filestore.FileStore.create(tmp.dir)
 
         tmp1 = TempDir()
         tmp2 = TempDir()
-        fs1 = filestore.FileStore(tmp1.dir)
-        fs2 = filestore.FileStore(tmp2.dir)
+        fs1 = filestore.FileStore.create(tmp1.dir)
+        fs2 = filestore.FileStore.create(tmp2.dir)
 
         with self.assertRaises(TypeError) as cm:
             fs.copy(ID)

=== modified file 'filestore/tests/run.py'
--- filestore/tests/run.py	2013-02-22 02:14:23 +0000
+++ filestore/tests/run.py	2013-05-15 00:48:33 +0000
@@ -22,6 +22,7 @@
 """
 Run `filestore` unit tests.
 """
+
 import sys
 from os import path
 from unittest import TestLoader, TextTestRunner
@@ -34,9 +35,12 @@
     'filestore',
     'filestore.protocols',
     'filestore.misc',
+    'filestore.migration',
     'filestore.tests',
+    'filestore.tests.run',
     'filestore.tests.test_protocols',
-    'filestore.tests.test_misc'
+    'filestore.tests.test_misc',
+    'filestore.tests.test_migration',
 )
 
 

=== added file 'filestore/tests/test_migration.py'
--- filestore/tests/test_migration.py	1970-01-01 00:00:00 +0000
+++ filestore/tests/test_migration.py	2013-05-15 00:48:33 +0000
@@ -0,0 +1,548 @@
+# filestore: dmedia hashing protocol and file layout
+# Copyright (C) 2013 Novacut Inc
+#
+# This file is part of `filestore`.
+#
+# `filestore` is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option) any
+# later version.
+#
+# `filestore` 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 Affero General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Affero General Public License along
+# with `filestore`.  If not, see <http://www.gnu.org/licenses/>.
+#
+# Authors:
+#   Jason Gerard DeRose <[e-mail]>
+
+"""
+Unit tests for the `filestore.migration` module.
+"""
+
+from unittest import TestCase
+import os
+from os import path
+import stat
+import time
+import json
+import shutil
+
+import dbase32
+from dbase32 import rfc3548
+
+import filestore
+from filestore import migration, misc
+
+from . import TempDir
+
+
+class TestConstants(TestCase):
+    def test_B32ALPHABET(self):
+        self.assertIsInstance(migration.B32ALPHABET, str)
+        self.assertEqual(len(migration.B32ALPHABET), 32)
+        self.assertEqual(len(set(migration.B32ALPHABET)), 32)
+        self.assertEqual(migration.B32ALPHABET,
+            ''.join(sorted(migration.B32ALPHABET))
+        )
+        self.assertEqual(migration.B32ALPHABET,
+            ''.join(sorted(rfc3548.B32_FORWARD))
+        )
+
+    def test_B32NAMES(self):
+        self.assertIsInstance(migration.B32NAMES, tuple)
+        self.assertEqual(len(migration.B32NAMES), 1024)
+        self.assertEqual(len(set(migration.B32NAMES)), 1024)
+        self.assertEqual(migration.B32NAMES,
+            tuple(sorted(migration.B32NAMES))
+        )
+        for name in migration.B32NAMES:
+            self.assertIsInstance(name, str)
+            self.assertEqual(len(name), 2)
+            self.assertTrue(name.isupper() or name.isnumeric())
+            self.assertTrue(set(name).issubset(migration.B32ALPHABET))
+
+    def test_NAMES_DIFF(self):
+        self.assertIsInstance(migration.NAMES_DIFF, tuple)
+        self.assertEqual(len(migration.NAMES_DIFF), 124)
+        self.assertEqual(len(set(migration.NAMES_DIFF)), 124)
+        self.assertEqual(migration.NAMES_DIFF,
+            tuple(sorted(migration.NAMES_DIFF))
+        )
+        for name in migration.NAMES_DIFF:
+            self.assertIsInstance(name, str)
+            self.assertEqual(len(name), 2)
+            self.assertTrue(name.isupper() or name.isnumeric())
+            self.assertIn(name, migration.B32NAMES)
+            self.assertNotIn(name, filestore.DB32NAMES)
+
+
+class TestFunctions(TestCase):        
+    def test_is_v0_files(self):
+        v0 = TempDir()
+        for name in migration.B32NAMES:
+            v0.mkdir(name)
+        self.assertIs(migration.is_v0_files(v0.dir), True)
+        v1 = TempDir()
+        for name in filestore.DB32NAMES:
+            v1.mkdir(name)
+        self.assertIs(migration.is_v0_files(v1.dir), False)
+        tmp = TempDir()
+        fs = filestore.FileStore.create(tmp.dir)
+        files = tmp.join('.dmedia', 'files')
+        self.assertTrue(path.isdir(files))
+        self.assertIs(migration.is_v0_files(files), False)
+
+    def test_b32_to_db32(self):
+        for i in range(100):
+            data = os.urandom(15)
+            b32 = rfc3548.b32enc(data)
+            db32 = dbase32.db32enc(data)
+            self.assertEqual(migration.b32_to_db32(b32), db32)
+
+    def test_v0_doc_to_v1(self):
+        doc = {
+            "_id": "4RNPIS23VFWZIOZDTPNHHENA", 
+            "copies": 1, 
+            "plugin": "filestore", 
+            "time": 1359461597.704514, 
+            "type": "dmedia/store"
+        }
+        self.assertEqual(migration.v0_doc_to_v1(doc), {
+            "_id": "VKGIBLTUO8PSBHS6MIGAA7G3", 
+            "copies": 1, 
+            "plugin": "filestore", 
+            "time": 1359461597.704514, 
+            "type": "dmedia/store"
+        })
+
+
+class TestMigration(TestCase):
+    def check_dir(self, fullname):
+        self.assertEqual(path.abspath(fullname), fullname)
+        st = os.stat(fullname, follow_symlinks=False)
+        self.assertTrue(stat.S_ISDIR(st.st_mode), fullname)
+        self.assertEqual(stat.S_IMODE(st.st_mode), 0o777, fullname)
+
+    def check_file(self, fullname):
+        self.assertEqual(path.abspath(fullname), fullname)
+        st = os.stat(fullname, follow_symlinks=False)
+        self.assertTrue(stat.S_ISREG(st.st_mode), fullname)
+        self.assertEqual(stat.S_IMODE(st.st_mode), 0o444, fullname)
+
+    def test_init(self):
+        tmp = TempDir()
+        m = migration.Migration(tmp.dir)
+        self.assertEqual(m.parentdir, tmp.dir)
+        self.assertEqual(m.basedir, tmp.join(filestore.DOTNAME))
+        self.assertEqual(m.files, tmp.join(filestore.DOTNAME, 'files'))
+        self.assertEqual(m.files0, tmp.join(filestore.DOTNAME, 'files0'))
+        self.assertEqual(m.store, tmp.join(filestore.DOTNAME, 'store.json'))
+        self.assertEqual(m.store0, tmp.join(filestore.DOTNAME, 'store0.json'))
+        self.assertEqual(m.filestore, tmp.join(filestore.DOTNAME, 'filestore.json'))
+
+    def test_needs_migration(self):
+        tmp = TempDir()
+        m = migration.Migration(tmp.dir)
+        self.assertIs(m.needs_migration(), False)
+        tmp.mkdir(filestore.DOTNAME)
+        self.assertFalse(path.exists(m.filestore))
+        self.assertFalse(path.exists(m.files))
+        self.assertIs(m.needs_migration(), False)
+        self.check_file(m.filestore)
+        self.check_dir(m.files)
+
+        # When there was a V0 files/ layout:
+        tmp = TempDir()
+        tmp.mkdir(filestore.DOTNAME)
+        m = migration.Migration(tmp.dir)
+        m.create_v0_files()
+        self.assertFalse(path.exists(m.filestore))
+        self.assertFalse(path.exists(m.files0))
+        self.assertIs(m.needs_migration(), True)
+        self.check_file(m.filestore)
+        self.check_dir(m.files0)
+        self.check_dir(m.files)
+
+        # Again, after "soft" migration was already done:
+        self.assertIs(m.needs_migration(), True)
+        self.check_file(m.filestore)
+        self.check_dir(m.files0)
+        self.check_dir(m.files)
+
+        # Remove files0, one more test:
+        shutil.rmtree(m.files0)
+        self.assertIs(m.needs_migration(), False)
+        self.check_file(m.filestore)
+        self.assertFalse(path.exists(m.files0))
+        self.check_dir(m.files)
+
+    def test_build_v0_simulation(self):
+        V0 = misc.load_data('V0')
+        V1 = misc.load_data('V1')
+        tmp = TempDir()
+        m = migration.Migration(tmp.dir)
+        doc = m.build_v0_simulation()
+        self.assertIsInstance(doc, dict)
+        old_id = doc['_id']
+
+        # First run, before rehashing has been done:
+        id_map1 = {}
+        ch_map = {}
+        for (v0_id, v1_id, v1_ch) in m:
+            id_map1[v0_id] = v1_id
+            self.assertIsInstance(v1_ch, filestore.ContentHash)
+            self.assertEqual(v1_ch.id, v1_id)
+            ch_map[v1_id] = v1_ch
+        self.assertEqual(len(id_map1), 6)
+        self.assertEqual(len(ch_map), 6)
+        self.assertEqual(len(set(id_map1.values())), 6)
+        for (key, v0_id) in V0['root_hashes'].items():
+            self.assertEqual(id_map1[v0_id], V1['root_hashes'][key])
+
+        # Second run, after ID mapping via our "broken" symlinks is in place:
+        id_map2 = {}
+        for (v0_id, v1_id, v1_ch) in m:
+            id_map2[v0_id] = v1_id
+            self.assertIsNone(v1_ch)
+        self.assertEqual(id_map2, id_map1)
+
+        # See if we get a valid V1 FileStore layout:
+        fs = filestore.FileStore(tmp.dir)
+        self.assertEqual(migration.b32_to_db32(old_id), fs.id)
+        fs.check_layout()
+        ids = [st.id for st in fs]
+        self.assertEqual(sorted(V1['root_hashes'].values()), ids)
+        self.assertEqual(sorted(ch_map.keys()), ids)
+        for (_id, ch) in ch_map.items():
+            self.assertEqual(fs.verify(_id), ch)
+
+    def test_join(self):
+        tmp = TempDir()
+        m = migration.Migration(tmp.dir)
+
+        # Cannot have empty parts:
+        with self.assertRaises(ValueError) as cm:
+            m.join()
+        self.assertEqual(str(cm.exception), 'Cannot have empty parts')
+
+        part1 = dbase32.random_id()
+        self.assertEqual(m.join(part1),
+            tmp.join(filestore.DOTNAME, part1)
+        )
+        part2 = dbase32.random_id()
+        self.assertEqual(m.join(part1, part2),
+            tmp.join(filestore.DOTNAME, part1, part2)
+        )
+        part3 = dbase32.random_id()
+        self.assertEqual(m.join(part1, part2, part3),
+            tmp.join(filestore.DOTNAME, part1, part2, part3)
+        )
+
+    def test_mkdir(self):
+        tmp = TempDir()
+        m = migration.Migration(tmp.dir)
+        part1 = dbase32.random_id()
+        part2 = dbase32.random_id()
+
+        # It shouldn't create basedir
+        with self.assertRaises(FileNotFoundError) as cm:
+            m.mkdir(part1)
+        self.assertEqual(cm.exception.filename,
+            tmp.join(filestore.DOTNAME, part1)
+        )
+        tmp.mkdir(filestore.DOTNAME)
+
+        # Cannot have empty parts:
+        with self.assertRaises(ValueError) as cm:
+            m.mkdir()
+        self.assertEqual(str(cm.exception), 'Cannot have empty parts')
+
+        # Test with 1st dir:
+        d1 = m.mkdir(part1)
+        self.assertEqual(d1, tmp.join(filestore.DOTNAME, part1))
+        self.check_dir(d1)
+        with self.assertRaises(FileExistsError) as cm:
+            m.mkdir(part1)
+        self.assertEqual(cm.exception.filename, d1)
+
+        # Test with 2nd dir:
+        d2 = m.mkdir(part1, part2)
+        self.assertEqual(d2, tmp.join(filestore.DOTNAME, part1, part2))
+        self.check_dir(d2)
+        with self.assertRaises(FileExistsError) as cm:
+            m.mkdir(part1, part2)
+        self.assertEqual(cm.exception.filename, d2)
+
+    def test_write(self):
+        doc = {
+            '_id': dbase32.random_id(),
+            'time': time.time(),
+            'type': 'dmedia/store',
+            'plugin': 'filestore', 
+            'copies': 1, 
+        }
+        text = json.dumps(doc)
+        name = dbase32.random_id(10).lower() + '.json'
+        tmp = TempDir()
+        m = migration.Migration(tmp.dir)
+
+        # It shouldn't create basedir
+        with self.assertRaises(FileNotFoundError) as cm:
+            m.write(name, text)
+        self.assertEqual(cm.exception.filename,
+            tmp.join(filestore.DOTNAME, name)
+        )
+        tmp.mkdir(filestore.DOTNAME)
+
+        # Should work when file doesn't already exist:
+        f = m.write(name, text)
+        self.assertEqual(f, tmp.join(filestore.DOTNAME, name))
+        self.check_file(f)
+        self.assertEqual(open(f, 'r').read(), text)
+
+        # But fail when the file does exists:
+        with self.assertRaises(FileExistsError) as cm:
+            m.write(name, 'different text')
+        self.assertEqual(cm.exception.filename, f)
+        self.check_file(f)
+        self.assertEqual(open(f, 'r').read(), text)
+
+    def test_load_v0_doc(self):
+        doc = {
+            '_id': rfc3548.random_id(),
+            'time': time.time(),
+            'type': 'dmedia/store',
+            'plugin': 'filestore', 
+            'copies': 1, 
+        }
+        doc0 = {
+            '_id': rfc3548.random_id(),
+            'time': time.time(),
+            'type': 'dmedia/store',
+            'plugin': 'filestore', 
+            'copies': 1, 
+        }
+
+        tmp = TempDir()
+        tmp.mkdir(filestore.DOTNAME)
+        m = migration.Migration(tmp.dir)
+        self.assertIsNone(m.load_v0_doc())
+
+        # Should load store.json if it is the only one presest:
+        m.write('store.json', json.dumps(doc))
+        self.assertEqual(m.load_v0_doc(), doc)
+
+        # But should load store0.json if *both* are presest:
+        m.write('store0.json', json.dumps(doc0))
+        self.assertEqual(m.load_v0_doc(), doc0)
+
+        # Likewise, should load store0.json if it is the only one presest:
+        tmp = TempDir()
+        tmp.mkdir(filestore.DOTNAME)
+        m = migration.Migration(tmp.dir)
+        self.assertIsNone(m.load_v0_doc())
+        m.write('store0.json', json.dumps(doc0))
+        self.assertEqual(m.load_v0_doc(), doc0)
+
+    def test_get_v1_doc(self):
+        tmp = TempDir()
+        tmp.mkdir(filestore.DOTNAME)
+        m = migration.Migration(tmp.dir)
+
+        new1 = m.get_v1_doc()
+        filestore.check_doc(new1)
+        new2 = m.get_v1_doc()
+        filestore.check_doc(new2)
+        self.assertNotEqual(new1['_id'], new2['_id'])
+
+        # store.json, not isdb32(old_id):
+        tmp = TempDir()
+        tmp.mkdir(filestore.DOTNAME)
+        m = migration.Migration(tmp.dir)
+        _id = 'Z' * 24  # Z is not in DB32ALPHABET
+        ts = time.time()
+        old = {'_id': _id, 'time': ts, 'copies': 1}
+        m.write('store.json', json.dumps(old))
+        new = m.get_v1_doc()
+        filestore.check_doc(new)
+        self.assertEqual(new, {
+            '_id': 'S' * 24,
+            'time': ts,
+            'type': 'dmedia/store',
+            'plugin': 'filestore',
+            'copies': 1,
+        })
+
+        # store.json, old['migrated'] is True:
+        tmp = TempDir()
+        tmp.mkdir(filestore.DOTNAME)
+        m = migration.Migration(tmp.dir)
+        _id = 'A' * 24  # A is in both DB32ALPHABET and B32ALPHABET
+        ts = time.time()
+        old = {'_id': _id, 'time': ts, 'copies': 2, 'migrated': True}
+        m.write('store.json', json.dumps(old))
+        new = m.get_v1_doc()
+        filestore.check_doc(new)
+        self.assertEqual(new, {
+            '_id': _id,
+            'time': ts,
+            'type': 'dmedia/store',
+            'plugin': 'filestore',
+            'copies': 2,
+        })
+
+        # store.json, not isb32(old_id):
+        tmp = TempDir()
+        tmp.mkdir(filestore.DOTNAME)
+        m = migration.Migration(tmp.dir)
+        _id = '9' * 24  # 9 is not in B32ALPHABET
+        ts = time.time()
+        old = {'_id': _id, 'time': ts, 'copies': 0}
+        m.write('store.json', json.dumps(old))
+        new = m.get_v1_doc()
+        filestore.check_doc(new)
+        self.assertEqual(new, {
+            '_id': _id,
+            'time': ts,
+            'type': 'dmedia/store',
+            'plugin': 'filestore',
+            'copies': 0,
+        })
+
+        # store.json, ambigous last case:
+        tmp = TempDir()
+        tmp.mkdir(filestore.DOTNAME)
+        m = migration.Migration(tmp.dir)
+        _id = 'A' * 24  # A is in both DB32ALPHABET and B32ALPHABET
+        ts = time.time()
+        old = {'_id': _id, 'time': ts, 'copies': 1}
+        m.write('store.json', json.dumps(old))
+        new = m.get_v1_doc()
+        filestore.check_doc(new)
+        self.assertEqual(new, {
+            '_id': '3' * 24,
+            'time': ts,
+            'type': 'dmedia/store',
+            'plugin': 'filestore',
+            'copies': 1,
+        })
+
+        # store0.json is always interpreted as a V0, Base32 doc:
+        tmp = TempDir()
+        tmp.mkdir(filestore.DOTNAME)
+        m = migration.Migration(tmp.dir)
+        v0_id = rfc3548.random_id()
+        v1_id = migration.b32_to_db32(v0_id)
+        self.assertNotEqual(v0_id, v1_id)
+        ts = time.time()
+        old = {'_id': v0_id, 'time': ts, 'copies': 1}
+        m.write('store0.json', json.dumps(old))
+        new = m.get_v1_doc()
+        filestore.check_doc(new)
+        self.assertEqual(new, {
+            '_id': v1_id,
+            'time': ts,
+            'type': 'dmedia/store',
+            'plugin': 'filestore',
+            'copies': 1,
+        })
+
+        # store0.json always takes precedence over store.json:
+        _id = '8' * 24  # 8 is not in B32ALPHABET
+        old = {'_id': _id, 'time': 1234.5678, 'copies': 1}
+        m.write('store.json', json.dumps(old))
+        self.assertEqual(m.get_v1_doc(), new)
+
+    def test_v0_path(self):
+        tmp = TempDir()
+        m = migration.Migration(tmp.dir)
+        for i in range(100):
+            _id = rfc3548.random_id(30)
+            self.assertEqual(m.v0_path(_id),
+                tmp.join(filestore.DOTNAME, 'files0', _id[:2], _id[2:])
+            )
+
+    def test_v1_path(self):
+        tmp = TempDir()
+        m = migration.Migration(tmp.dir)
+        for i in range(100):
+            _id = dbase32.random_id(30)
+            self.assertEqual(m.v1_path(_id),
+                tmp.join(filestore.DOTNAME, 'files', _id[:2], _id[2:])
+            )
+
+    def test_create_v0_files(self):
+        tmp = TempDir()
+        m = migration.Migration(tmp.dir)
+
+        # It shouldn't create basedir
+        with self.assertRaises(FileNotFoundError) as cm:
+            m.create_v0_files()
+        self.assertEqual(cm.exception.filename,
+            tmp.join(filestore.DOTNAME, 'files')
+        )
+        tmp.mkdir(filestore.DOTNAME)
+
+        # Now it should work:
+        self.assertIsNone(m.create_v0_files())
+        files = tmp.join(filestore.DOTNAME, 'files')
+        self.check_dir(files)
+        for name in migration.B32NAMES:
+            self.check_dir(path.join(files, name))
+        self.assertEqual(sorted(os.listdir(files)), list(migration.B32NAMES))
+
+        # Should fail if .dmedia/files/ already exists:
+        with self.assertRaises(FileExistsError) as cm:
+            m.create_v0_files()
+        self.assertEqual(cm.exception.filename, files)
+
+    def test_create_v1_files(self):
+        tmp = TempDir()
+        m = migration.Migration(tmp.dir)
+
+        # It shouldn't create basedir
+        with self.assertRaises(FileNotFoundError) as cm:
+            m.create_v1_files()
+        self.assertEqual(cm.exception.filename,
+            tmp.join(filestore.DOTNAME, 'files')
+        )
+        tmp.mkdir(filestore.DOTNAME)
+
+        # Now it should work:
+        self.assertIsNone(m.create_v1_files())
+        files = tmp.join(filestore.DOTNAME, 'files')
+        self.check_dir(files)
+        for name in filestore.DB32NAMES:
+            self.check_dir(path.join(files, name))
+        self.assertEqual(sorted(os.listdir(files)), list(filestore.DB32NAMES))
+
+        # Should fail if .dmedia/files/ already exists:
+        with self.assertRaises(FileExistsError) as cm:
+            m.create_v1_files()
+        self.assertEqual(cm.exception.filename, files)
+
+    def test_move_v0_files_to_files0(self):
+        tmp = TempDir()
+        tmp.mkdir(filestore.DOTNAME)
+        m = migration.Migration(tmp.dir)
+        m.create_v0_files()
+        self.assertIsNone(m.move_v0_files_to_files0())
+
+        # Check files/
+        files = tmp.join(filestore.DOTNAME, 'files')
+        self.check_dir(files)
+        for name in filestore.DB32NAMES:
+            self.check_dir(path.join(files, name))
+        self.assertEqual(sorted(os.listdir(files)), list(filestore.DB32NAMES))
+
+        # Check files0/
+        files0 = tmp.join(filestore.DOTNAME, 'files0')
+        self.check_dir(files0)
+        for name in migration.B32NAMES:
+            self.check_dir(path.join(files0, name))
+        self.assertEqual(sorted(os.listdir(files0)), list(migration.B32NAMES))
+

=== modified file 'filestore/tests/test_misc.py'
--- filestore/tests/test_misc.py	2013-04-28 17:02:28 +0000
+++ filestore/tests/test_misc.py	2013-05-15 00:48:33 +0000
@@ -30,7 +30,7 @@
 from hashlib import md5
 from skein import skein512
 
-from dbase32 import db32enc, db32dec
+from dbase32 import db32enc, db32dec, isdb32, random_id, RANDOM_B32LEN
 from dbase32.rfc3548 import b32enc, b32dec
 
 from . import TempDir
@@ -250,24 +250,91 @@
 
 
 class TestTempFileStore(TestCase):
+    def test_create(self):
+        """
+        Test the TempFileStore.create() classmethod.
+        """
+        fs = misc.TempFileStore.create()
+        self.assertIsInstance(fs, filestore.FileStore)
+        self.assertIsInstance(fs, misc.TempFileStore)
+        self.assertTrue(fs.parentdir.startswith('/tmp/TempFileStore.'))
+        self.assertIsInstance(fs.id, str)
+        self.assertEqual(len(fs.id), RANDOM_B32LEN)
+        self.assertTrue(isdb32(fs.id))
+        self.assertIsInstance(fs.copies, int)
+        self.assertEqual(fs.copies, 1)
+
+        store_id = random_id()
+        fs = misc.TempFileStore.create(store_id, 2)
+        self.assertIsInstance(fs, filestore.FileStore)
+        self.assertIsInstance(fs, misc.TempFileStore)
+        self.assertTrue(fs.parentdir.startswith('/tmp/TempFileStore.'))
+        self.assertIsInstance(fs.id, str)
+        self.assertEqual(len(fs.id), RANDOM_B32LEN)
+        self.assertTrue(isdb32(fs.id))
+        self.assertEqual(fs.id, store_id)
+        self.assertIsInstance(fs.copies, int)
+        self.assertEqual(fs.copies, 2)
+
+        label = 'Dmedia' + random_id(10).lower()
+        fs = misc.TempFileStore.create(label=label)
+        self.assertIsInstance(fs, filestore.FileStore)
+        self.assertIsInstance(fs, misc.TempFileStore)
+        self.assertTrue(fs.parentdir.startswith('/tmp/TempFileStore.'))
+        self.assertIsInstance(fs.id, str)
+        self.assertEqual(len(fs.id), RANDOM_B32LEN)
+        self.assertTrue(isdb32(fs.id))
+        self.assertIsInstance(fs.copies, int)
+        self.assertEqual(fs.copies, 1)
+        self.assertEqual(fs.doc['label'], label)
+
     def test_init(self):
         fs = misc.TempFileStore()
         self.assertIsInstance(fs, filestore.FileStore)
         self.assertTrue(fs.parentdir.startswith('/tmp/TempFileStore.'))
-        self.assertIsNone(fs.id)
-        self.assertEqual(fs.copies, 0)
+        self.assertIsInstance(fs.id, str)
+        self.assertEqual(len(fs.id), RANDOM_B32LEN)
+        self.assertTrue(isdb32(fs.id))
+        self.assertIsInstance(fs.copies, int)
+        self.assertEqual(fs.copies, 1)
 
-        fs = misc.TempFileStore('foobar', 2)
+        store_id = random_id()
+        fs = misc.TempFileStore(store_id, 2)
         self.assertIsInstance(fs, filestore.FileStore)
         self.assertTrue(fs.parentdir.startswith('/tmp/TempFileStore.'))
-        self.assertEqual(fs.id, 'foobar')
+        self.assertIsInstance(fs.id, str)
+        self.assertEqual(len(fs.id), RANDOM_B32LEN)
+        self.assertTrue(isdb32(fs.id))
+        self.assertEqual(fs.id, store_id)
+        self.assertIsInstance(fs.copies, int)
         self.assertEqual(fs.copies, 2)
 
-        fs = misc.TempFileStore(_id='hooray', copies=3)
+        label = 'Dmedia' + random_id(10).lower()
+        fs = misc.TempFileStore(label=label)
         self.assertIsInstance(fs, filestore.FileStore)
         self.assertTrue(fs.parentdir.startswith('/tmp/TempFileStore.'))
-        self.assertEqual(fs.id, 'hooray')
-        self.assertEqual(fs.copies, 3)
+        self.assertIsInstance(fs.id, str)
+        self.assertEqual(len(fs.id), RANDOM_B32LEN)
+        self.assertTrue(isdb32(fs.id))
+        self.assertIsInstance(fs.copies, int)
+        self.assertEqual(fs.copies, 1)
+        self.assertEqual(fs.doc['label'], label)
+
+    def test_repr(self):
+        # With auto-generated ID:
+        fs = misc.TempFileStore()
+        self.assertTrue(isdb32(fs.id) and len(fs.id) == 24)
+        self.assertEqual(repr(fs),
+            'TempFileStore({!r}, {!r})'.format(fs.parentdir, fs.id)
+        )
+
+        # With explicit ID:
+        store_id = random_id()
+        fs = misc.TempFileStore(store_id)
+        self.assertEqual(fs.id, store_id)
+        self.assertEqual(repr(fs),
+            'TempFileStore({!r}, {!r})'.format(fs.parentdir, fs.id)
+        )
 
     def test_del(self):
         fs = misc.TempFileStore()