Forward warning for unoptimal index

docs/couchdb-quirks.md

@@ -34,6 +34,24 @@ reasons. In general, you can follow these two rules of thumb:
    omit the `sort` operator on the query (except if you want the `descending`
    order).
 
+### Warnings for slow requests
+
+When requesting a mango index, CouchDB can use an index. But there are also
+cases where no index can be used, or where the index is not optimal. Let's
+see the different scenarios:
+
+- CouchDB does use an index, it will respond with a warning, and cozy-stack
+  will transform this warning in an error, as developers should really avoid
+  this issue
+
+- CouchDB can use an index for the selector but not for the sort, it will
+  respond with an error, and the cozy-stack will just forward the error
+
+- CouchDB can use an index, but will still look at much more documents in
+  the index that what will be in the response (it happens with `$or` and `$in`
+  operators, which should be avoided), CouchDB 3+ will send a warning and the
+  cozy-stack will forward the documents and the warning to the client.
+
 ### Comparison of strings
 
 Comparison of strings is done using ICU which implements the Unicode Collation

pkg/couchdb/couchdb.go

@@ -913,8 +913,8 @@ func findDocsRaw(db prefixer.Prefixer, doctype string, req interface{}, results
 		}
 		return nil, err
 	}
-	if !ignoreUnoptimized && response.Warning != "" {
-		// Developer should not rely on unoptimized index.
+	if !ignoreUnoptimized && strings.Contains(response.Warning, "matching index found") {
+		// Developers should not rely on fullscan with no index.
 		return nil, unoptimalError()
 	}
 	if response.Bookmark == "nil" {

pkg/jsonapi/data.go

@@ -18,6 +18,7 @@ type Object interface {
 // in JSON-API land
 type Meta struct {
 	Rev            string                  `json:"rev,omitempty"`
+	Warning        string                  `json:"warning,omitempty"`
 	Count          *int                    `json:"count,omitempty"`
 	ExecutionStats *couchdb.ExecutionStats `json:"execution_stats,omitempty"`
 }

pkg/jsonapi/jsonapi.go

@@ -73,12 +73,14 @@ func Data(c echo.Context, statusCode int, o Object, links *LinksList) error {
 // DataList can be called to send an multiple-value answer with a
 // JSON-API document contains multiple objects.
 func DataList(c echo.Context, statusCode int, objs []Object, links *LinksList) error {
-	return DataListWithTotal(c, statusCode, len(objs), objs, links, nil)
+	count := len(objs)
+	meta := Meta{Count: &count}
+	return DataListWithMeta(c, statusCode, meta, objs, links)
 }
 
-// DataListWithTotal can be called to send a list of Object with a different
-// meta:count, useful to indicate total number of results with pagination.
-func DataListWithTotal(c echo.Context, statusCode, total int, objs []Object, links *LinksList, executionStats *couchdb.ExecutionStats) error {
+// DataListWithMeta can be called to send a list of Objects with meta like a
+// count, useful to indicate total number of results with pagination.
+func DataListWithMeta(c echo.Context, statusCode int, meta Meta, objs []Object, links *LinksList) error {
 	objsMarshaled := make([]json.RawMessage, len(objs))
 	for i, o := range objs {
 		j, err := MarshalObject(o)
@@ -95,7 +97,7 @@ func DataListWithTotal(c echo.Context, statusCode, total int, objs []Object, lin
 
 	doc := Document{
 		Data:  (*json.RawMessage)(&data),
-		Meta:  &Meta{Count: &total, ExecutionStats: executionStats},
+		Meta:  &meta,
 		Links: links,
 	}
 

web/data/data.go

@@ -374,6 +374,9 @@ func findDocuments(c echo.Context) error {
 	if resp.ExecutionStats != nil {
 		out["execution_stats"] = resp.ExecutionStats
 	}
+	if resp.Warning != "" {
+		out["warning"] = resp.Warning
+	}
 	return c.JSON(http.StatusOK, out)
 }
 

web/files/files.go

@@ -1516,7 +1516,12 @@ func FindFilesMango(c echo.Context) error {
 		}
 	}
 
-	return jsonapi.DataListWithTotal(c, http.StatusOK, total, out, &links, resp.ExecutionStats)
+	meta := jsonapi.Meta{
+		Count:          &total,
+		ExecutionStats: resp.ExecutionStats,
+		Warning:        resp.Warning,
+	}
+	return jsonapi.DataListWithMeta(c, http.StatusOK, meta, out, &links)
 }
 
 var allowedChangesParams = map[string]bool{

web/files/paginated.go

@@ -241,7 +241,8 @@ func dirDataList(c echo.Context, statusCode int, doc *vfs.DirDoc) error {
 		links.Next = next
 	}
 
-	return jsonapi.DataListWithTotal(c, statusCode, count, included, &links, nil)
+	meta := jsonapi.Meta{Count: &count}
+	return jsonapi.DataListWithMeta(c, statusCode, meta, included, &links)
 }
 
 // NewFile creates an instance of file struct from a vfs.FileDoc document.