Reintroduce WebsocketAcceptor interface

Provides separation between RequestHandler and the different purpose of these classes.

src/AllowOriginAcceptor.php

@@ -7,10 +7,9 @@
 use Amp\Http\HttpStatus;
 use Amp\Http\Server\ErrorHandler;
 use Amp\Http\Server\Request;
-use Amp\Http\Server\RequestHandler;
 use Amp\Http\Server\Response;
 
-final class AllowOriginAcceptor implements RequestHandler
+final class AllowOriginAcceptor implements WebsocketAcceptor
 {
  use ForbidCloning;
  use ForbidSerialization;
@@ -21,16 +20,16 @@ final class AllowOriginAcceptor implements RequestHandler
  public function __construct(
  private readonly array $allowOrigins,
  private readonly ErrorHandler $errorHandler = new Internal\UpgradeErrorHandler(),
- private readonly RequestHandler $acceptor = new Rfc6455Acceptor(),
+ private readonly WebsocketAcceptor $acceptor = new Rfc6455Acceptor(),
  ) {
  }
 
- public function handleRequest(Request $request): Response
+ public function handleHandshake(Request $request): Response
  {
  if (!\in_array($request->getHeader('origin'), $this->allowOrigins, true)) {
  return $this->errorHandler->handleError(HttpStatus::FORBIDDEN, 'Origin forbidden', $request);
  }
 
- return $this->acceptor->handleRequest($request);
+ return $this->acceptor->handleHandshake($request);
  }
 }

src/Rfc6455Acceptor.php

@@ -7,11 +7,10 @@
 use Amp\Http\HttpStatus;
 use Amp\Http\Server\ErrorHandler;
 use Amp\Http\Server\Request;
-use Amp\Http\Server\RequestHandler;
 use Amp\Http\Server\Response;
 use function Amp\Websocket\generateAcceptFromKey;
 
-final class Rfc6455Acceptor implements RequestHandler
+final class Rfc6455Acceptor implements WebsocketAcceptor
 {
  use ForbidCloning;
  use ForbidSerialization;
@@ -20,31 +19,7 @@ public function __construct(private readonly ErrorHandler $errorHandler = new In
  {
  }
 
- /**
- * Respond to websocket handshake requests.
- *
- * If a websocket application doesn't wish to impose any special constraints on the
- * handshake it doesn't have to do anything beyond the request handling provided by this
- * method. All valid websocket handshakes will be accepted. It is recommended to do
- * validation of the connected client as part of the protocol implemented by the
- * {@see WebsocketClientHandler}.
- *
- * Most web applications should check the `origin` header to restrict access,
- * as websocket connections aren't subject to browser's same-origin-policy. See
- * {@see AllowOriginAcceptor} for such an implementation.
- *
- * Another implementation may delegate to this class to accept the client, then validate
- * the cookies of the request before returning the response provided by the method
- * below, or returning an error response.
- *
- * The response provided by the upgrade handler is made available to {@see WebsocketClientHandler::handleClient()}.
- *
- * @param Request $request The HTTP request that instigated the handshake
- *
- * @return Response Return a response with a status code other than
- * {@link HttpStatus::SWITCHING_PROTOCOLS} to deny the handshake request.
- */
- public function handleRequest(Request $request): Response
+ public function handleHandshake(Request $request): Response
  {
  if ($request->getMethod() !== 'GET') {
  $response = $this->errorHandler->handleError(HttpStatus::METHOD_NOT_ALLOWED, request: $request);

src/Websocket.php

@@ -30,7 +30,7 @@ final class Websocket implements RequestHandler
  public function __construct(
  HttpServer $httpServer,
  private readonly PsrLogger $logger,
- private readonly RequestHandler $acceptor,
+ private readonly WebsocketAcceptor $acceptor,
  private readonly WebsocketClientHandler $clientHandler,
  private readonly WebsocketClientFactory $clientFactory = new Rfc6455ClientFactory(),
  ) {
@@ -42,7 +42,7 @@ public function __construct(
 
  public function handleRequest(Request $request): Response
  {
- $response = $this->acceptor->handleRequest($request);
+ $response = $this->acceptor->handleHandshake($request);
 
  if ($response->getStatus() !== HttpStatus::SWITCHING_PROTOCOLS) {
  $response->removeHeader('sec-websocket-accept');

src/WebsocketAcceptor.php

@@ -0,0 +1,36 @@
+<?php declare(strict_types=1);
+
+namespace Amp\Websocket\Server;
+
+use Amp\Http\Server\Request;
+use Amp\Http\Server\Response;
+
+interface WebsocketAcceptor
+{
+ /**
+ * Respond to websocket handshake requests.
+ *
+ * If a websocket application doesn't wish to impose any special constraints on the
+ * handshake it may use {@see Rfc6455Acceptor} to accept websocket requests on a
+ * {@see Websocket} endpoint.
+ *
+ * Most web applications should check the `origin` header to restrict access,
+ * as websocket connections aren't subject to browser's same-origin-policy. See
+ * {@see AllowOriginAcceptor} for such an implementation.
+ *
+ * This method provides an opportunity to set application-specific headers, including
+ * cookies, on the websocket response. Although any non-101 status code can be used
+ * to reject the websocket connection, we generally recommended using a 4xx status
+ * code that is descriptive of why the handshake was rejected. It is suggested that an
+ * instance of {@see ErrorHandler} is used to generate such a response.
+ *
+ * The response provided by the upgrade handler is made available to
+ * {@see WebsocketClientHandler::handleClient()}.
+ *
+ * @param Request $request The websocket HTTP handshake request.
+ *
+ * @return Response Return a response with a status code other than
+ * {@link HttpStatus::SWITCHING_PROTOCOLS} to deny the handshake request.
+ */
+ public function handleHandshake(Request $request): Response;
+}

test/WebsocketTest.php

@@ -10,7 +10,6 @@
 use Amp\Http\Server\Driver\Client as HttpClient;
 use Amp\Http\Server\ErrorHandler;
 use Amp\Http\Server\Request;
-use Amp\Http\Server\RequestHandler;
 use Amp\Http\Server\Response;
 use Amp\Http\Server\SocketHttpServer;
 use Amp\PHPUnit\AsyncTestCase;
@@ -110,20 +109,20 @@ public function handleClient(WebsocketClient $client, Request $request, Response
  */
  public function testHandshake(Request $request, int $status, array $expectedHeaders = []): void
  {
- $upgradeHandler = $this->createMock(RequestHandler::class);
+ $acceptor = $this->createMock(WebsocketAcceptor::class);
 
  $delegateHandler = new Rfc6455Acceptor();
- $upgradeHandler->expects(self::once())
- ->method('handleRequest')
- ->willReturnCallback($delegateHandler->handleRequest(...));
+ $acceptor->expects(self::once())
+ ->method('handleHandshake')
+ ->willReturnCallback($delegateHandler->handleHandshake(...));
 
  $logger = new NullLogger();
  $server = SocketHttpServer::createForDirectAccess($logger);
  $server->expose(new Socket\InternetAddress('127.0.0.1', 0));
  $websocket = new Websocket(
  httpServer: $server,
  logger: $logger,
- acceptor: $upgradeHandler,
+ acceptor: $acceptor,
  clientHandler: $this->createMock(WebsocketClientHandler::class),
  );
  $server->start($websocket, $this->createMock(ErrorHandler::class));