make HEAD/GET method rewrite configurable

.github/workflows/build-and-test.yml

@@ -11,12 +11,11 @@ jobs:
       # Run tests on all OS's and HHVM versions, even if one fails
       fail-fast: false
       matrix:
-        os: [ ubuntu ]
+        os: [ ubuntu-20.04 ]
         hhvm:
-          - '4.128'
-          - latest
-          - nightly
-    runs-on: ${{matrix.os}}-latest
+          - '4.153'
+          - '4.168'
+    runs-on: ${{matrix.os}}
     steps:
       - uses: actions/checkout@v2
       - name: Create branch for version alias

README.md

@@ -48,7 +48,7 @@ final class BaseRouterExample extends BaseRouter<TResponder> {
 ```
 
 Simplified for conciseness - see
-[`examples/BaseRouterExample.php`](examples/BaseRouterExample.php) for
+[`examples/RunBaseRouterExample.php`](examples/RunBaseRouterExample.php) for
 full executable example.
 
 UriPatterns
@@ -87,7 +87,7 @@ $link = UserPageController::getUriBuilder()
 ```
 
 These examples are simplified for conciseness - see
-[`examples/UriPatternsExample.php`](examples/UriPatternsExample.php) for
+[`examples/RunUriPatternsExample.php`](examples/RunUriPatternsExample.php) for
 full executable example.
 
 Codegen

composer.json

@@ -5,7 +5,7 @@
   "keywords": ["hack", "router", "routing", "hhvm"],
   "homepage": "https://github.com/hhvm/hack-router",
   "require": {
-    "hhvm": "^4.128",
+    "hhvm": "^4.153",
     "facebook/hack-http-request-response-interfaces": "^0.2|^0.3"
   },
   "extra": {

examples/RunBaseRouterExample.php

@@ -0,0 +1,30 @@
+<?hh // strict
+/*
+ *  Copyright (c) 2015-present, Facebook, Inc.
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the MIT license found in the
+ *  LICENSE file in the root directory of this source tree.
+ *
+ */
+
+/***********
+ * IF YOU EDIT THIS FILE also update the snippet in README.md
+ ***********/
+
+namespace Facebook\HackRouter\Examples\BaseRouterExample;
+
+<<__EntryPoint>>
+function main(): noreturn {
+  require_once __DIR__.'/../vendor/autoload.hack';
+  \Facebook\AutoloadMap\initialize();
+
+  $router = new BaseRouterExample();
+  foreach (get_example_inputs() as $input) {
+    list($method, $path) = $input;
+
+    list($responder, $params) = $router->routeMethodAndPath($method, $path);
+    \printf("%s %s\n\t%s\n", $method, $path, $responder(dict($params)));
+  }
+  exit(0);
+}

examples/RunUriPatternsExample.php

@@ -0,0 +1,30 @@
+<?hh // strict
+/*
+ *  Copyright (c) 2015-present, Facebook, Inc.
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the MIT license found in the
+ *  LICENSE file in the root directory of this source tree.
+ *
+ */
+
+/***********
+ * IF YOU EDIT THIS FILE also update the snippet in README.md
+ ***********/
+
+namespace Facebook\HackRouter\Examples\UrlPatternsExample;
+
+use type Facebook\HackRouter\HttpMethod;
+
+<<__EntryPoint>>
+function main(): void {
+  require_once __DIR__.'/../vendor/autoload.hack';
+  \Facebook\AutoloadMap\initialize();
+
+  $router = new UriPatternsExample();
+  foreach (get_example_paths() as $path) {
+    list($controller, $params) =
+      $router->routeMethodAndPath(HttpMethod::GET, $path);
+    \printf("GET %s\n\t%s\n", $path, (new $controller($params))->getResponse());
+  }
+}

examples/BaseRouterExample.php → examples/lib/BaseRouterExample.php

@@ -14,26 +14,22 @@
 
 namespace Facebook\HackRouter\Examples\BaseRouterExample;
 
-require_once(__DIR__.'/../vendor/hh_autoload.php');
-
 use type Facebook\HackRouter\{BaseRouter, HttpMethod};
 
 /** This can be whatever you want; in this case, it's a
  * callable, but classname<MyWebControllerBase> is also a
  * common choice.
  */
-type TResponder = (function(dict<string, string>):string);
+type TResponder = (function(dict<string, string>): string);
 
 final class BaseRouterExample extends BaseRouter<TResponder> {
   <<__Override>>
   protected function getRoutes(
   ): ImmMap<HttpMethod, ImmMap<string, TResponder>> {
     return ImmMap {
       HttpMethod::GET => ImmMap {
-        '/' =>
-          ($_params) ==> 'Hello, world',
-        '/user/{user_name}' =>
-          ($params) ==> 'Hello, '.$params['user_name'],
+        '/' => ($_params) ==> 'Hello, world',
+        '/user/{user_name}' => ($params) ==> 'Hello, '.$params['user_name'],
       },
       HttpMethod::POST => ImmMap {
         '/' => ($_params) ==> 'Hello, POST world',
@@ -50,20 +46,3 @@ function get_example_inputs(): ImmVector<(HttpMethod, string)> {
     tuple(HttpMethod::POST, '/'),
   };
 }
-
-<<__EntryPoint>>
-function main(): noreturn {
-  $router = new BaseRouterExample();
-  foreach (get_example_inputs() as $input) {
-    list($method, $path) = $input;
-
-    list($responder, $params) = $router->routeMethodAndPath($method, $path);
-    \printf(
-      "%s %s\n\t%s\n",
-      $method,
-      $path,
-      $responder(dict($params)),
-    );
-  }
-  exit(0);
-}

examples/UriPatternsExample.php → examples/lib/UriPatternsExample.php

@@ -14,16 +14,14 @@
 
 namespace Facebook\HackRouter\Examples\UrlPatternsExample;
 
-require_once(__DIR__.'/../vendor/hh_autoload.php');
-
-use   type Facebook\HackRouter\{
+use type Facebook\HackRouter\{
   BaseRouter,
   GetFastRoutePatternFromUriPattern,
   GetUriBuilderFromUriPattern,
   HasUriPattern,
   HttpMethod,
   RequestParameters,
-  UriPattern
+  UriPattern,
 };
 
 <<__ConsistentConstruct>>
@@ -38,12 +36,10 @@ final protected function getRequestParameters(): RequestParameters {
     return $this->uriParameters;
   }
 
-  public function __construct(
-    ImmMap<string, string> $uri_parameter_values,
-  ) {
+  public function __construct(ImmMap<string, string> $uri_parameter_values) {
     $this->uriParameters = new RequestParameters(
       static::getUriPattern()->getParameters(),
-      ImmVector { },
+      ImmVector {},
       $uri_parameter_values,
     );
   }
@@ -86,8 +82,7 @@ public static function getControllers(): ImmVector<TResponder> {
   }
 
   <<__Override>>
-  public function getRoutes(
-  ): ImmMap<HttpMethod, ImmMap<string, TResponder>> {
+  public function getRoutes(): ImmMap<HttpMethod, ImmMap<string, TResponder>> {
     $urls_to_controllers = dict[];
     foreach (self::getControllers() as $controller) {
       $pattern = $controller::getFastRoutePattern();
@@ -107,21 +102,3 @@ function get_example_paths(): ImmVector<string> {
       ->getPath(),
   };
 }
-
-function main(): void {
-  $router = new UriPatternsExample();
-  foreach (get_example_paths() as $path) {
-    list($controller, $params) = $router->routeMethodAndPath(
-      HttpMethod::GET,
-      $path,
-    );
-    \printf(
-      "GET %s\n\t%s\n",
-      $path,
-      (new $controller($params))->getResponse(),
-    );
-  }
-}
-
-/* HH_IGNORE_ERROR[1002] top-level statement in strict file */
-main();

src/http-exceptions/InternalServerErrorException.php

@@ -10,5 +10,5 @@
 
 namespace Facebook\HackRouter;
 
-class InternalServerErrorException extends HttpException {
-}
+// HHAST_IGNORE_ERROR[FinalOrAbstractClass] @see UnknownRouterException.
+class InternalServerErrorException extends HttpException {}

src/http-exceptions/MethodNotAllowedException.php

@@ -10,6 +10,7 @@
 
 namespace Facebook\HackRouter;
 
+// HHAST_IGNORE_ERROR[FinalOrAbstractClass] maybe extended outside this library.
 class MethodNotAllowedException extends HttpException {
   public function __construct(
     protected keyset<HttpMethod> $allowed,

src/http-exceptions/NotFoundException.php

@@ -10,5 +10,5 @@
 
 namespace Facebook\HackRouter;
 
-class NotFoundException extends HttpException {
-}
+// HHAST_IGNORE_ERROR[FinalOrAbstractClass] maybe extended outside this library.
+class NotFoundException extends HttpException {}

src/request-parameters/EnumRequestParameter.php

@@ -12,17 +12,21 @@
 
 use namespace HH\Lib\{Str, Vec};
 
+/**
+ * WARNING: hh_client will not infer a correct enum type when given `SomeEnum::class`.
+ * @see RequestParametersTest::testInvalidEnumParamToUri() (grep for @ref)
+ * `EnumRequestParameterExplicit` is typesafe, so you can use that instead.
+ */
+// HHAST_IGNORE_ERROR[FinalOrAbstractClass] comment above.
 class EnumRequestParameter<T> extends TypedUriParameter<T> {
   public function __construct(
-    /* HH_FIXME[2053] */
-    private classname<\HH\BuiltinEnum<T>> $enumClass,
+    private \HH\enumname<T> $enumClass,
     string $name,
   ) {
     parent::__construct($name);
   }
 
-  /* HH_FIXME[2053] */
-  final public function getEnumName(): classname<\HH\BuiltinEnum<T>> {
+  final public function getEnumName(): \HH\enumname<T> {
     return $this->enumClass;
   }
 
@@ -42,7 +46,7 @@ public function assert(string $input): T {
   public function getRegExpFragment(): ?string {
     $class = $this->enumClass;
     $values = $class::getValues();
-    $sub_fragments = Vec\map($values, $value ==> \preg_quote((string) $value));
+    $sub_fragments = Vec\map($values, $value ==> \preg_quote((string)$value));
     return '(?:'.Str\join($sub_fragments, '|').')';
   }
 }

src/request-parameters/EnumRequestParameterExplicit.php

@@ -0,0 +1,14 @@
+<?hh // strict
+/*
+ *  Copyright (c) 2015-present, Facebook, Inc.
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the MIT license found in the
+ *  LICENSE file in the root directory of this source tree.
+ *
+ */
+
+namespace Facebook\HackRouter;
+
+final class EnumRequestParameterExplicit<<<__Explicit>> T>
+  extends EnumRequestParameter<T> {}

src/request-parameters/RequestParameterGetters.php

@@ -32,8 +32,7 @@ final public function getOptionalInt(string $name): ?int {
   }
 
   final public function getEnum<TValue>(
-    /* HH_FIXME[2053] */
-    classname<\HH\BuiltinEnum<TValue>> $class,
+    \HH\enumname<TValue> $class,
     string $name,
   ): TValue {
     $value = $this->getEnumImpl(
@@ -45,8 +44,7 @@ classname<\HH\BuiltinEnum<TValue>> $class,
   }
 
   final public function getOptionalEnum<TValue>(
-    /* HH_FIXME[2053] */
-    classname<\HH\BuiltinEnum<TValue>> $class,
+    \HH\enumname<TValue> $class,
     string $name,
   ): ?TValue {
     return $this->getEnumImpl(
@@ -58,8 +56,7 @@ classname<\HH\BuiltinEnum<TValue>> $class,
 
   final private function getEnumImpl<TValue>(
     EnumRequestParameter<TValue> $spec,
-    /* HH_FIXME[2053] */
-    classname<\HH\BuiltinEnum<TValue>> $class,
+    \HH\enumname<TValue> $class,
     string $name,
   ): ?TValue {
     invariant(

src/request-parameters/RequestParametersBase.php

@@ -24,9 +24,8 @@ public function __construct(
     KeyedTraversable<string, string> $values,
   ) {
     $this->values = new ImmMap($values);
-    $spec_vector_to_map = (
-      Traversable<RequestParameter> $specs
-    ) ==> Dict\pull($specs, $it ==> $it, $it ==> $it->getName());
+    $spec_vector_to_map = (Traversable<RequestParameter> $specs) ==>
+      Dict\pull($specs, $it ==> $it, $it ==> $it->getName());
 
     $this->requiredSpecs = $spec_vector_to_map($required_specs);
     $this->optionalSpecs = $spec_vector_to_map($optional_specs);
@@ -63,14 +62,13 @@ classname<T> $class,
   ): T {
     $spec = $specs[$name];
     invariant(
-      /* HH_FIXME[4162] need reified generics */
       \is_a($spec, $class),
       'Expected %s to be a %s, got %s',
       $name,
       $class,
       \get_class($spec),
     );
-    return /* HH_FIXME[4110] */ $spec;
+    return \HH\FIXME\UNSAFE_CAST<RequestParameter, T>($spec, 'is_a($spec, $class) ~= $spec is T');
   }
 
   final protected function getSimpleTyped<T>(

src/router/BaseRouter.php

@@ -14,6 +14,13 @@
 use function Facebook\AutoloadMap\Generated\is_dev;
 
 abstract class BaseRouter<+TResponder> {
+  private bool $useGetResponderForHead;
+
+  public function __construct(?BaseRouterOptions $options = null) {
+    $this->useGetResponderForHead =
+      Shapes::idx($options, 'use_get_responder_for_head', true);
+  }
+
   abstract protected function getRoutes(
   ): KeyedContainer<HttpMethod, KeyedContainer<string, TResponder>>;
 
@@ -33,7 +40,9 @@ final public function routeMethodAndPath(
       }
 
       if (
-        $method === HttpMethod::HEAD && $allowed === keyset[HttpMethod::GET]
+        $this->useGetResponderForHead &&
+        $method === HttpMethod::HEAD &&
+        $allowed === keyset[HttpMethod::GET]
       ) {
         list($responder, $data) = $resolver->resolve(HttpMethod::GET, $path);
         $data = Dict\map($data, \urldecode<>);

src/router/BaseRouterOptions.php

@@ -0,0 +1,16 @@
+<?hh // strict
+
+/*
+ *  Copyright (c) 2015-present, Facebook, Inc.
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the MIT license found in the
+ *  LICENSE file in the root directory of this source tree.
+ *
+ */
+
+namespace Facebook\HackRouter;
+
+type BaseRouterOptions = shape(
+  ?'use_get_responder_for_head' => bool,
+);