Flesh out Conduit parameter types for Owners + CustomFields

Summary:
Ref T9964. Fill in more parameter types and descriptions.

(No date support yet since it's a bit more involved.)

Test Plan: {F1024022}

Reviewers: chad

Reviewed By: chad

Maniphest Tasks: T9964

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

src/__phutil_library_map__.php

@@ -223,6 +223,7 @@ phutil_register_library_map(array(
     'ConduitAPIRequest' => 'applications/conduit/protocol/ConduitAPIRequest.php',
     'ConduitAPIResponse' => 'applications/conduit/protocol/ConduitAPIResponse.php',
     'ConduitApplicationNotInstalledException' => 'applications/conduit/protocol/exception/ConduitApplicationNotInstalledException.php',
+    'ConduitBoolParameterType' => 'applications/conduit/parametertype/ConduitBoolParameterType.php',
     'ConduitCall' => 'applications/conduit/call/ConduitCall.php',
     'ConduitCallTestCase' => 'applications/conduit/call/__tests__/ConduitCallTestCase.php',
     'ConduitConnectConduitAPIMethod' => 'applications/conduit/method/ConduitConnectConduitAPIMethod.php',
@@ -232,6 +233,7 @@ phutil_register_library_map(array(
     'ConduitException' => 'applications/conduit/protocol/exception/ConduitException.php',
     'ConduitGetCapabilitiesConduitAPIMethod' => 'applications/conduit/method/ConduitGetCapabilitiesConduitAPIMethod.php',
     'ConduitGetCertificateConduitAPIMethod' => 'applications/conduit/method/ConduitGetCertificateConduitAPIMethod.php',
+    'ConduitIntParameterType' => 'applications/conduit/parametertype/ConduitIntParameterType.php',
     'ConduitListParameterType' => 'applications/conduit/parametertype/ConduitListParameterType.php',
     'ConduitLogGarbageCollector' => 'applications/conduit/garbagecollector/ConduitLogGarbageCollector.php',
     'ConduitMethodDoesNotExistException' => 'applications/conduit/protocol/exception/ConduitMethodDoesNotExistException.php',
@@ -244,6 +246,7 @@ phutil_register_library_map(array(
     'ConduitResultSearchEngineExtension' => 'applications/conduit/query/ConduitResultSearchEngineExtension.php',
     'ConduitSSHWorkflow' => 'applications/conduit/ssh/ConduitSSHWorkflow.php',
     'ConduitStringListParameterType' => 'applications/conduit/parametertype/ConduitStringListParameterType.php',
+    'ConduitStringParameterType' => 'applications/conduit/parametertype/ConduitStringParameterType.php',
     'ConduitTokenGarbageCollector' => 'applications/conduit/garbagecollector/ConduitTokenGarbageCollector.php',
     'ConduitUserListParameterType' => 'applications/conduit/parametertype/ConduitUserListParameterType.php',
     'ConpherenceColumnViewController' => 'applications/conpherence/controller/ConpherenceColumnViewController.php',
@@ -4072,6 +4075,7 @@ phutil_register_library_map(array(
     'ConduitAPIRequest' => 'Phobject',
     'ConduitAPIResponse' => 'Phobject',
     'ConduitApplicationNotInstalledException' => 'ConduitMethodNotFoundException',
+    'ConduitBoolParameterType' => 'ConduitListParameterType',
     'ConduitCall' => 'Phobject',
     'ConduitCallTestCase' => 'PhabricatorTestCase',
     'ConduitConnectConduitAPIMethod' => 'ConduitAPIMethod',
@@ -4081,6 +4085,7 @@ phutil_register_library_map(array(
     'ConduitException' => 'Exception',
     'ConduitGetCapabilitiesConduitAPIMethod' => 'ConduitAPIMethod',
     'ConduitGetCertificateConduitAPIMethod' => 'ConduitAPIMethod',
+    'ConduitIntParameterType' => 'ConduitListParameterType',
     'ConduitListParameterType' => 'ConduitParameterType',
     'ConduitLogGarbageCollector' => 'PhabricatorGarbageCollector',
     'ConduitMethodDoesNotExistException' => 'ConduitMethodNotFoundException',
@@ -4093,6 +4098,7 @@ phutil_register_library_map(array(
     'ConduitResultSearchEngineExtension' => 'PhabricatorSearchEngineExtension',
     'ConduitSSHWorkflow' => 'PhabricatorSSHWorkflow',
     'ConduitStringListParameterType' => 'ConduitListParameterType',
+    'ConduitStringParameterType' => 'ConduitListParameterType',
     'ConduitTokenGarbageCollector' => 'PhabricatorGarbageCollector',
     'ConduitUserListParameterType' => 'ConduitListParameterType',
     'ConpherenceColumnViewController' => 'ConpherenceController',

src/applications/conduit/parametertype/ConduitBoolParameterType.php

@@ -0,0 +1,36 @@
+<?php
+
+final class ConduitBoolParameterType
+  extends ConduitListParameterType {
+
+  protected function getParameterValue(array $request, $key) {
+    $value = parent::getParameterValue($request, $key);
+
+    if (!is_bool($value)) {
+      $this->raiseValidationException(
+        $request,
+        $key,
+        pht('Expected boolean (true or false), got something else.'));
+    }
+
+    return $value;
+  }
+
+  protected function getParameterTypeName() {
+    return 'bool';
+  }
+
+  protected function getParameterFormatDescriptions() {
+    return array(
+      pht('A boolean.'),
+    );
+  }
+
+  protected function getParameterExamples() {
+    return array(
+      'true',
+      'false',
+    );
+  }
+
+}

src/applications/conduit/parametertype/ConduitEpochParameterType.php

@@ -10,7 +10,14 @@ final class ConduitEpochParameterType
       $this->raiseValidationException(
         $request,
         $key,
-        pht('Expected integer, got something else.'));
+        pht('Expected epoch timestamp as integer, got something else.'));
+    }
+
+    if ($value <= 0) {
+      $this->raiseValidationException(
+        $request,
+        $key,
+        pht('Epoch timestamp must be larger than 0, got %d.', $value));
     }
 
     return $value;
@@ -28,9 +35,7 @@ final class ConduitEpochParameterType
 
   protected function getParameterExamples() {
     return array(
-      '["PHID-PROJ-1111"]',
+      '1450019509',
-      '["backend"]',
-      '["PHID-PROJ-2222", "frontend"]',
     );
   }
 

src/applications/conduit/parametertype/ConduitIntParameterType.php

@@ -0,0 +1,37 @@
+<?php
+
+final class ConduitIntParameterType
+  extends ConduitListParameterType {
+
+  protected function getParameterValue(array $request, $key) {
+    $value = parent::getParameterValue($request, $key);
+
+    if (!is_int($value)) {
+      $this->raiseValidationException(
+        $request,
+        $key,
+        pht('Expected integer, got something else.'));
+    }
+
+    return $value;
+  }
+
+  protected function getParameterTypeName() {
+    return 'int';
+  }
+
+  protected function getParameterFormatDescriptions() {
+    return array(
+      pht('An integer.'),
+    );
+  }
+
+  protected function getParameterExamples() {
+    return array(
+      '123',
+      '0',
+      '-345',
+    );
+  }
+
+}

src/applications/conduit/parametertype/ConduitStringParameterType.php

@@ -0,0 +1,35 @@
+<?php
+
+final class ConduitStringParameterType
+  extends ConduitListParameterType {
+
+  protected function getParameterValue(array $request, $key) {
+    $value = parent::getParameterValue($request, $key);
+
+    if (!is_string($value)) {
+      $this->raiseValidationException(
+        $request,
+        $key,
+        pht('Expected string, got something else.'));
+    }
+
+    return $value;
+  }
+
+  protected function getParameterTypeName() {
+    return 'string';
+  }
+
+  protected function getParameterFormatDescriptions() {
+    return array(
+      pht('A string.'),
+    );
+  }
+
+  protected function getParameterExamples() {
+    return array(
+      '"papaya"',
+    );
+  }
+
+}

src/applications/owners/query/PhabricatorOwnersPackageSearchEngine.php

@@ -21,19 +21,29 @@ final class PhabricatorOwnersPackageSearchEngine
         ->setLabel(pht('Authority'))
         ->setKey('authorityPHIDs')
         ->setAliases(array('authority', 'authorities'))
+        ->setConduitKey('owners')
+        ->setDescription(
+          pht('Search for packages with specific owners.'))
         ->setDatasource(new PhabricatorProjectOrUserDatasource()),
       id(new PhabricatorSearchDatasourceField())
         ->setLabel(pht('Repositories'))
         ->setKey('repositoryPHIDs')
+        ->setConduitKey('repositories')
         ->setAliases(array('repository', 'repositories'))
+        ->setDescription(
+          pht('Search for packages by included repositories.'))
         ->setDatasource(new DiffusionRepositoryDatasource()),
       id(new PhabricatorSearchStringListField())
         ->setLabel(pht('Paths'))
         ->setKey('paths')
-        ->setAliases(array('path')),
+        ->setAliases(array('path'))
+        ->setDescription(
+          pht('Search for packages affecting specific paths.')),
       id(new PhabricatorSearchCheckboxesField())
         ->setKey('statuses')
         ->setLabel(pht('Status'))
+        ->setDescription(
+          pht('Search for active or archived packages.'))
         ->setOptions(
           id(new PhabricatorOwnersPackage())
             ->getStatusNameMap()),

src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php

@@ -196,13 +196,13 @@ EOTEXT
       );
 
     $head_builtin = pht('Builtin Order');
-    $head_description = pht('Description');
+    $head_label = pht('Label');
     $head_columns = pht('Columns');
 
     $orders = $query->getBuiltinOrders();
 
     $table = array();
-    $table[] = "| {$head_builtin} | {$head_description} | {$head_columns} |";
+    $table[] = "| {$head_builtin} | {$head_label} | {$head_columns} |";
     $table[] = '|-----------------|---------------------|-----------------|';
     foreach ($orders as $key => $order) {
       $name = $order['name'];
@@ -310,6 +310,10 @@ These are the fields available on this object type:
 EOTEXT
       );
 
+    $head_key = pht('Key');
+    $head_type = pht('Type');
+    $head_description = pht('Description');
+
     $specs = $engine->getAllConduitFieldSpecifications();
 
     $table = array();

src/applications/search/field/PhabricatorSearchCustomFieldProxyField.php

@@ -63,4 +63,12 @@ final class PhabricatorSearchCustomFieldProxyField
       $this->getValue());
   }
 
+  public function getDescription() {
+    return $this->getCustomField()->getFieldDescription();
+  }
+
+  protected function newConduitParameterType() {
+    return $this->getCustomField()->getConduitSearchParameterType();
+  }
+
 }

src/applications/search/field/PhabricatorSearchDatasourceField.php

@@ -14,4 +14,8 @@ final class PhabricatorSearchDatasourceField
     return $this;
   }
 
+  protected function newConduitParameterType() {
+    return new ConduitStringListParameterType();
+  }
+
 }

src/infrastructure/customfield/field/PhabricatorCustomField.php

@@ -1337,6 +1337,17 @@ abstract class PhabricatorCustomField extends Phobject {
     return false;
   }
 
+  public function getConduitSearchParameterType() {
+    return $this->newConduitSearchParameterType();
+  }
+
+  protected function newConduitSearchParameterType() {
+    if ($this->proxy) {
+      return $this->proxy->newConduitSearchParameterType();
+    }
+    return null;
+  }
+
 
 /* -(  Herald  )------------------------------------------------------------- */
 

src/infrastructure/customfield/standard/PhabricatorStandardCustomField.php

@@ -463,4 +463,5 @@ abstract class PhabricatorStandardCustomField
     return $this->getFieldValue();
   }
 
+
 }

src/infrastructure/customfield/standard/PhabricatorStandardCustomFieldBool.php

@@ -133,4 +133,7 @@ final class PhabricatorStandardCustomFieldBool
     return new AphrontBoolHTTPParameterType();
   }
 
+  protected function newConduitSearchParameterType() {
+    return new ConduitBoolParameterType();
+  }
 }

src/infrastructure/customfield/standard/PhabricatorStandardCustomFieldDate.php

@@ -197,4 +197,9 @@ final class PhabricatorStandardCustomFieldDate
     return false;
   }
 
+  protected function newConduitSearchParameterType() {
+    // TODO: Build a new "pair<epoch|null, epoch|null>" type or similar.
+    return null;
+  }
+
 }

src/infrastructure/customfield/standard/PhabricatorStandardCustomFieldHeader.php

@@ -30,4 +30,8 @@ final class PhabricatorStandardCustomFieldHeader
     return $this->getFieldName();
   }
 
+  public function shouldAppearInApplicationSearch() {
+    return false;
+  }
+
 }

src/infrastructure/customfield/standard/PhabricatorStandardCustomFieldInt.php

@@ -116,5 +116,8 @@ final class PhabricatorStandardCustomFieldInt
     return new AphrontIntHTTPParameterType();
   }
 
+  protected function newConduitSearchParameterType() {
+    return new ConduitIntParameterType();
+  }
 
 }

src/infrastructure/customfield/standard/PhabricatorStandardCustomFieldLink.php

@@ -84,4 +84,7 @@ final class PhabricatorStandardCustomFieldLink
     return new AphrontStringHTTPParameterType();
   }
 
+  protected function newConduitSearchParameterType() {
+    return new ConduitStringListParameterType();
+  }
 }

src/infrastructure/customfield/standard/PhabricatorStandardCustomFieldRemarkup.php

@@ -99,5 +99,8 @@ final class PhabricatorStandardCustomFieldRemarkup
     return new AphrontStringHTTPParameterType();
   }
 
+  public function shouldAppearInApplicationSearch() {
+    return false;
+  }
 
 }

src/infrastructure/customfield/standard/PhabricatorStandardCustomFieldSelect.php

@@ -140,4 +140,7 @@ final class PhabricatorStandardCustomFieldSelect
     return new AphrontSelectHTTPParameterType();
   }
 
+  protected function newConduitSearchParameterType() {
+    return new ConduitStringListParameterType();
+  }
 }

src/infrastructure/customfield/standard/PhabricatorStandardCustomFieldText.php

@@ -67,4 +67,8 @@ final class PhabricatorStandardCustomFieldText
     return new AphrontStringHTTPParameterType();
   }
 
+  public function shouldAppearInApplicationSearch() {
+    return false;
+  }
+
 }

src/infrastructure/customfield/standard/PhabricatorStandardCustomFieldUsers.php

@@ -15,4 +15,8 @@ final class PhabricatorStandardCustomFieldUsers
     return new AphrontUserListHTTPParameterType();
   }
 
+  protected function newConduitSearchParameterType() {
+    return new ConduitUserListParameterType();
+  }
+
 }