From: Daira Hopwood <david-sarah@jacaranda.org>
Date: Thu, 18 Apr 2013 22:42:51 +0000 (+0100)
Subject: Add comments and a caveat in webapi.rst indicating that
X-Git-Tag: allmydata-tahoe-1.10.0b2~7
X-Git-Url: https://git.rkrishnan.org/specifications/%5B/%5D%20/(%5B%5E?a=commitdiff_plain;h=b06f8cd8d03a62396809393a3501771264fb5177;p=tahoe-lafs%2Ftahoe-lafs.git

Add comments and a caveat in webapi.rst indicating that
the needs-rebalancing field may be computed incorrectly. refs #1115, #1784, #1477

Signed-off-by: Daira Hopwood <david-sarah@jacaranda.org>
---

diff --git a/docs/frontends/webapi.rst b/docs/frontends/webapi.rst
index 9072ef28..046d2c59 100644
--- a/docs/frontends/webapi.rst
+++ b/docs/frontends/webapi.rst
@@ -1431,10 +1431,12 @@ mainly intended for developers.
     list-corrupt-shares: a list of "share locators", one for each share
                          that was found to be corrupt. Each share locator
                          is a list of (serverid, storage_index, sharenum).
-    needs-rebalancing: (bool) True if there are multiple shares on a single
-                       storage server, indicating a reduction in reliability
-                       that could be resolved by moving shares to new
-                       servers.
+    needs-rebalancing: (bool) This field is intended to be True iff
+                       reliability could be improved for this file by
+                       rebalancing, i.e. by moving some shares to other
+                       servers. It may be incorrect in some cases for
+                       Tahoe-LAFS up to and including v1.10, and its
+                       precise definition is expected to change.
     servers-responding: list of base32-encoded storage server identifiers,
                         one for each server which responded to the share
                         query.
diff --git a/src/allmydata/immutable/checker.py b/src/allmydata/immutable/checker.py
index 37d6a5ea..41000f7e 100644
--- a/src/allmydata/immutable/checker.py
+++ b/src/allmydata/immutable/checker.py
@@ -778,6 +778,7 @@ class Checker(log.PrefixingLogMixin):
         # The file needs rebalancing if the set of servers that have at least
         # one share is less than the number of uniquely-numbered shares
         # available.
+        # TODO: this may be wrong, see ticket #1115 comment:27 and ticket #1784.
         needs_rebalancing = bool(good_share_hosts < len(verifiedshares))
 
         cr = CheckResults(self._verifycap, SI,
diff --git a/src/allmydata/immutable/filenode.py b/src/allmydata/immutable/filenode.py
index 79e282d9..6b54b2d0 100644
--- a/src/allmydata/immutable/filenode.py
+++ b/src/allmydata/immutable/filenode.py
@@ -143,7 +143,10 @@ class CiphertextFileNode:
         good_hosts = len(reduce(set.union, sm.values(), set()))
         is_healthy = bool(len(sm) >= verifycap.total_shares)
         is_recoverable = bool(len(sm) >= verifycap.needed_shares)
+
+        # TODO: this may be wrong, see ticket #1115 comment:27 and ticket #1784.
         needs_rebalancing = bool(len(sm) >= verifycap.total_shares)
+
         prr = CheckResults(cr.get_uri(), cr.get_storage_index(),
                            healthy=is_healthy, recoverable=is_recoverable,
                            needs_rebalancing=needs_rebalancing,