Create a base api handler for authenticated web socket APIs

[3coins]

Problem

Current jupyter-server code doesn't have a base handler or utility for creating authenticated web socket APIs. An example of an authenticated web socket is present in AuthenticatedZMQStreamHandler.

jupyter_server/jupyter_server/base/zmqhandlers.py

Lines 303 to 348 in 77be2f5

	class AuthenticatedZMQStreamHandler(ZMQStreamHandler, JupyterHandler):
	def set_default_headers(self):
	"""Undo the set_default_headers in JupyterHandler
	which doesn't make sense for websockets
	"""
	pass
	def pre_get(self):
	"""Run before finishing the GET request
	Extend this method to add logic that should fire before
	the websocket finishes completing.
	"""
	# authenticate the request before opening the websocket
	user = self.get_current_user()
	if user is None:
	self.log.warning("Couldn't authenticate WebSocket connection")
	raise web.HTTPError(403)
	# authorize the user.
	if not self.authorizer:
	# Warn if there is not authorizer.
	warn_disabled_authorization()
	elif not self.authorizer.is_authorized(self, user, "execute", "kernels"):
	raise web.HTTPError(403)
	if self.get_argument("session_id", False):
	self.session.session = self.get_argument("session_id")
	else:
	self.log.warning("No session ID specified")
	async def get(self, *args, **kwargs):
	# pre_get can be a coroutine in subclasses
	# assign and yield in two step to avoid tornado 3 issues
	res = self.pre_get()
	await res
	res = super().get(*args, **kwargs)
	await res
	def initialize(self):
	self.log.debug("Initializing websocket connection %s", self.request.path)
	self.session = Session(config=self.config)
	def get_compression_options(self):
	return self.settings.get("websocket_compression_options", None)

When working with authenticated web socket APIs, this code will be duplicated for each handler.

Proposed Solution

• Create a new WebSocketAPIHandler that new APIs can inherit from. This will contain functions that all jupyter web sockets should inherit, for example, set_default_handlers, initialize, get_compression_options etc.
• Create a AuthWebSocketAPIHandler that additionally adds authentication for web sockets. This will contain functions, that add authentication for web sockets, for example pre_get and get.

Additional context

[welcome]

Thank you for opening your first issue in this project! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out Jupyter's Code of Conduct. Also, please try to follow the issue template as it helps other other community members to contribute more effectively.

You can meet the other Jovyans by joining our Discourse forum. There is also an intro thread there where you can stop by and say Hi! 👋

Welcome to the Jupyter community! 🎉

[3coins]

cc @bollwyvl @Zsailer
I also noticed a WebSocketMixin which has common web socket options; is this something we should move into the base handler as part of this effort?

jupyter_server/jupyter_server/base/zmqhandlers.py

Lines 121 to 230 in 77be2f5

	class WebSocketMixin:
	"""Mixin for common websocket options"""
	ping_callback = None
	last_ping = 0
	last_pong = 0
	stream = None
	@property
	def ping_interval(self):
	"""The interval for websocket keep-alive pings.
	Set ws_ping_interval = 0 to disable pings.
	"""
	return self.settings.get("ws_ping_interval", WS_PING_INTERVAL)
	@property
	def ping_timeout(self):
	"""If no ping is received in this many milliseconds,
	close the websocket connection (VPNs, etc. can fail to cleanly close ws connections).
	Default is max of 3 pings or 30 seconds.
	"""
	return self.settings.get("ws_ping_timeout", max(3 * self.ping_interval, WS_PING_INTERVAL))
	def check_origin(self, origin=None):
	"""Check Origin == Host or Access-Control-Allow-Origin.
	Tornado >= 4 calls this method automatically, raising 403 if it returns False.
	"""
	if self.allow_origin == "*" or (
	hasattr(self, "skip_check_origin") and self.skip_check_origin()
	):
	return True
	host = self.request.headers.get("Host")
	if origin is None:
	origin = self.get_origin()
	# If no origin or host header is provided, assume from script
	if origin is None or host is None:
	return True
	origin = origin.lower()
	origin_host = urlparse(origin).netloc
	# OK if origin matches host
	if origin_host == host:
	return True
	# Check CORS headers
	if self.allow_origin:
	allow = self.allow_origin == origin
	elif self.allow_origin_pat:
	allow = bool(re.match(self.allow_origin_pat, origin))
	else:
	# No CORS headers deny the request
	allow = False
	if not allow:
	self.log.warning(
	"Blocking Cross Origin WebSocket Attempt. Origin: %s, Host: %s",
	origin,
	host,
	)
	return allow
	def clear_cookie(self, *args, **kwargs):
	"""meaningless for websockets"""
	pass
	def open(self, *args, **kwargs):
	self.log.debug("Opening websocket %s", self.request.path)
	# start the pinging
	if self.ping_interval > 0:
	loop = ioloop.IOLoop.current()
	self.last_ping = loop.time() # Remember time of last ping
	self.last_pong = self.last_ping
	self.ping_callback = ioloop.PeriodicCallback(
	self.send_ping,
	self.ping_interval,
	)
	self.ping_callback.start()
	return super().open(*args, **kwargs)
	def send_ping(self):
	"""send a ping to keep the websocket alive"""
	if self.ws_connection is None and self.ping_callback is not None:
	self.ping_callback.stop()
	return
	if self.ws_connection.client_terminated:
	self.close()
	return
	# check for timeout on pong. Make sure that we really have sent a recent ping in
	# case the machine with both server and client has been suspended since the last ping.
	now = ioloop.IOLoop.current().time()
	since_last_pong = 1e3 * (now - self.last_pong)
	since_last_ping = 1e3 * (now - self.last_ping)
	if since_last_ping < 2 * self.ping_interval and since_last_pong > self.ping_timeout:
	self.log.warning("WebSocket ping timeout after %i ms.", since_last_pong)
	self.close()
	return
	self.ping(b"")
	self.last_ping = now
	def on_pong(self, data):
	self.last_pong = ioloop.IOLoop.current().time()