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 9072ef2896eaebb9d275b0a5692778bd7ba32780..046d2c59e493cf795937895a7c2c4a57013694ab 100644 (file)
--- 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 37d6a5ea4de07bc2e105a16738ac596ad0343699..41000f7e0d14df68ae0a5bf0faedefeb017867aa 100644 (file)
--- 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 79e282d90e232a2645b56e7b14cf1a765fd463e3..6b54b2d03287c73ad08a660e28e851c26dc9d5f7 100644 (file)
--- 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,