Drive conduit result ordering through Query order specifications

Summary:
Ref T7803. Ref T5873. Allows Query methods to expose orderings from the underlying Query class nearly-for-free.

Callers can specify a string to use a builtin ordering, or an array to use a low-level column ordering.

Test Plan: {F368236}

Reviewers: btrahan

Reviewed By: btrahan

Subscribers: epriestley

Maniphest Tasks: T5873, T7803

Differential Revision: https://secure.phabricator.com/D12381

src/applications/conduit/controller/PhabricatorConduitConsoleController.php

@@ -119,7 +119,65 @@ final class PhabricatorConduitConsoleController
     $form_box = id(new PHUIObjectBoxView())
       ->setHeader($header)
       ->setFormErrors($errors)
-      ->setForm($form);
+      ->appendChild($form);
+
+    $content = array();
+
+    $query = $method->newQueryObject();
+    if ($query) {
+      $orders = $query->getBuiltinOrders();
+
+      $rows = array();
+      foreach ($orders as $key => $order) {
+        $rows[] = array(
+          $key,
+          $order['name'],
+          implode(', ', $order['vector']),
+        );
+      }
+
+      $table = id(new AphrontTableView($rows))
+        ->setHeaders(
+          array(
+            pht('Key'),
+            pht('Description'),
+            pht('Columns'),
+          ))
+        ->setColumnClasses(
+          array(
+            'pri',
+            '',
+            'wide',
+          ));
+      $content[] = id(new PHUIObjectBoxView())
+        ->setHeaderText(pht('Builtin Orders'))
+        ->appendChild($table);
+
+      $columns = $query->getOrderableColumns();
+
+      $rows = array();
+      foreach ($columns as $key => $column) {
+        $rows[] = array(
+          $key,
+          idx($column, 'unique') ? pht('Yes') : pht('No'),
+        );
+      }
+
+      $table = id(new AphrontTableView($rows))
+        ->setHeaders(
+          array(
+            pht('Key'),
+            pht('Unique'),
+          ))
+        ->setColumnClasses(
+          array(
+            'pri',
+            'wide',
+          ));
+      $content[] = id(new PHUIObjectBoxView())
+        ->setHeaderText(pht('Column Orders'))
+        ->appendChild($table);
+    }
 
     $crumbs = $this->buildApplicationCrumbs();
     $crumbs->addTextCrumb($method->getAPIMethodName());
@@ -128,6 +186,7 @@ final class PhabricatorConduitConsoleController
       array(
         $crumbs,
         $form_box,
+        $content,
       ),
       array(
         'title' => $method->getAPIMethodName(),

src/applications/conduit/method/ConduitAPIMethod.php

@@ -26,7 +26,15 @@ abstract class ConduitAPIMethod
   public function __construct() {}
 
   public function getParamTypes() {
-    return $this->defineParamTypes();
+    $types = $this->defineParamTypes();
+
+    $query = $this->newQueryObject();
+    if ($query) {
+      $types['order'] = 'order';
+      $types += $this->getPagerParamTypes();
+    }
+
+    return $types;
   }
 
   public function getReturnType() {
@@ -253,6 +261,48 @@ abstract class ConduitAPIMethod
   }
 
 
+/* -(  Implementing Query Methods  )----------------------------------------- */
+
+
+  public function newQueryObject() {
+    return null;
+  }
+
+
+  protected function newQueryForRequest(ConduitAPIRequest $request) {
+    $query = $this->newQueryObject();
+
+    if (!$query) {
+      throw new Exception(
+        pht(
+          'You can not call newQueryFromRequest() in this method ("%s") '.
+          'because it does not implement newQueryObject().',
+          get_class($this)));
+    }
+
+    if (!($query instanceof PhabricatorCursorPagedPolicyAwareQuery)) {
+      throw new Exception(
+        pht(
+          'Call to method newQueryObject() did not return an object of class '.
+          '"%s".',
+          'PhabricatorCursorPagedPolicyAwareQuery'));
+    }
+
+    $query->setViewer($request->getUser());
+
+    $order = $request->getValue('order');
+    if ($order !== null) {
+      if (is_scalar($order)) {
+        $query->setOrder($order);
+      } else {
+        $query->setOrderVector($order);
+      }
+    }
+
+    return $query;
+  }
+
+
 /* -(  PhabricatorPolicyInterface  )----------------------------------------- */
 
 

src/applications/repository/conduit/RepositoryQueryConduitAPIMethod.php

@@ -19,6 +19,10 @@ final class RepositoryQueryConduitAPIMethod
     return pht('Query repositories.');
   }
 
+  public function newQueryObject() {
+    return new PhabricatorRepositoryQuery();
+  }
+
   protected function defineParamTypes() {
     return array(
       'ids' => 'optional list<int>',
@@ -35,8 +39,7 @@ final class RepositoryQueryConduitAPIMethod
   }
 
   protected function execute(ConduitAPIRequest $request) {
-    $query = id(new PhabricatorRepositoryQuery())
+    $query = $this->newQueryForRequest($request);
-      ->setViewer($request->getUser());
 
     $ids = $request->getValue('ids', array());
     if ($ids) {
@@ -68,7 +71,8 @@ final class RepositoryQueryConduitAPIMethod
       $query->withUUIDs($uuids);
     }
 
-    $repositories = $query->execute();
+    $pager = $this->newPager($request);
+    $repositories = $query->executeWithCursorPager($pager);
 
     $results = array();
     foreach ($repositories as $repository) {