feat(core): streams (denoland#12596)

This allows resources to be "streams" by implementing read/write/shutdown. These streams are implicit since their nature (read/write/duplex) isn't known until called, but we could easily add another method to explicitly tag resources as streams.

`op_read/op_write/op_shutdown` are now builtin ops provided by `deno_core`

Note: this current implementation is simple & straightforward but it results in an additional alloc per read/write call

Closes denoland#12556

cli/tests/unit/metrics_test.ts

@@ -16,7 +16,7 @@ unitTest(async function metrics() {
  assert(m1.bytesSentControl === 0);
  assert(m1.bytesSentData === 0);
  assert(m1.bytesReceived === 0);
- const m1OpWrite = m1.ops["op_write_async"];
+ const m1OpWrite = m1.ops["op_write"];
  assert(m1OpWrite.opsDispatchedAsync > 0);
  assert(m1OpWrite.opsCompletedAsync > 0);
  assert(m1OpWrite.bytesSentControl === 0);
@@ -31,7 +31,7 @@ unitTest(async function metrics() {
  assert(m2.bytesSentControl === m1.bytesSentControl);
  assert(m2.bytesSentData === 0);
  assert(m2.bytesReceived === m1.bytesReceived);
- const m2OpWrite = m2.ops["op_write_async"];
+ const m2OpWrite = m2.ops["op_write"];
  assert(m2OpWrite.opsDispatchedAsync > m1OpWrite.opsDispatchedAsync);
  assert(m2OpWrite.opsCompletedAsync > m1OpWrite.opsCompletedAsync);
  assert(m2OpWrite.bytesSentControl === m1OpWrite.bytesSentControl);

cli/tests/unit/opcall_test.ts

@@ -35,8 +35,7 @@ declare global {
 unitTest(async function opsAsyncBadResource() {
  try {
  const nonExistingRid = 9999;
- await Deno.core.opAsync(
- "op_read_async",
+ await Deno.core.read(
  nonExistingRid,
  new Uint8Array(0),
  );

core/01_core.js

@@ -146,6 +146,18 @@
  return ObjectFromEntries(opSync("op_resources"));
  }
 
+ function read(rid, buf) {
+ return opAsync("op_read", rid, buf);
+ }
+
+ function write(rid, buf) {
+ return opAsync("op_write", rid, buf);
+ }
+
+ function shutdown(rid) {
+ return opAsync("op_shutdown", rid);
+ }
+
  function close(rid) {
  opSync("op_close", rid);
  }
@@ -191,6 +203,9 @@
  ops,
  close,
  tryClose,
+ read,
+ write,
+ shutdown,
  print,
  resources,
  metrics,

core/examples/http_bench_json_ops.js

@@ -19,28 +19,11 @@ function accept(serverRid) {
  return Deno.core.opAsync("accept", serverRid);
 }
 
-/**
- * Reads a packet from the rid, presumably an http request. data is ignored.
- * Returns bytes read.
- */
-function read(rid, data) {
- return Deno.core.opAsync("read", rid, data);
-}
-
-/** Writes a fixed HTTP response to the socket rid. Returns bytes written. */
-function write(rid, data) {
- return Deno.core.opAsync("write", rid, data);
-}
-
-function close(rid) {
- Deno.core.opSync("close", rid);
-}
-
 async function serve(rid) {
  try {
  while (true) {
- await read(rid, requestBuf);
- await write(rid, responseBuf);
+ await Deno.core.read(rid, requestBuf);
+ await Deno.core.write(rid, responseBuf);
  }
  } catch (e) {
  if (
@@ -50,7 +33,7 @@ async function serve(rid) {
  throw e;
  }
  }
- close(rid);
+ Deno.core.close(rid);
 }
 
 async function main() {

core/examples/http_bench_json_ops.rs

@@ -1,6 +1,7 @@
 // Copyright 2018-2021 the Deno authors. All rights reserved. MIT license.
 use deno_core::error::AnyError;
 use deno_core::AsyncRefCell;
+use deno_core::AsyncResult;
 use deno_core::CancelHandle;
 use deno_core::CancelTryFuture;
 use deno_core::JsRuntime;
@@ -77,19 +78,33 @@ struct TcpStream {
 }
 
 impl TcpStream {
- async fn read(self: Rc<Self>, buf: &mut [u8]) -> Result<usize, Error> {
+ async fn read(
+ self: Rc<Self>,
+ mut buf: ZeroCopyBuf,
+ ) -> Result<usize, AnyError> {
  let mut rd = RcRef::map(&self, |r| &r.rd).borrow_mut().await;
  let cancel = RcRef::map(self, |r| &r.cancel);
- rd.read(buf).try_or_cancel(cancel).await
+ rd.read(&mut buf)
+ .try_or_cancel(cancel)
+ .await
+ .map_err(AnyError::from)
  }
 
- async fn write(self: Rc<Self>, buf: &[u8]) -> Result<usize, Error> {
+ async fn write(self: Rc<Self>, buf: ZeroCopyBuf) -> Result<usize, AnyError> {
  let mut wr = RcRef::map(self, |r| &r.wr).borrow_mut().await;
- wr.write(buf).await
+ wr.write(&buf).await.map_err(AnyError::from)
  }
 }
 
 impl Resource for TcpStream {
+ fn read(self: Rc<Self>, buf: ZeroCopyBuf) -> AsyncResult<usize> {
+ Box::pin(self.read(buf))
+ }
+
+ fn write(self: Rc<Self>, buf: ZeroCopyBuf) -> AsyncResult<usize> {
+ Box::pin(self.write(buf))
+ }
+
  fn close(self: Rc<Self>) {
  self.cancel.cancel()
  }
@@ -109,10 +124,7 @@ impl From<tokio::net::TcpStream> for TcpStream {
 fn create_js_runtime() -> JsRuntime {
  let mut runtime = JsRuntime::new(Default::default());
  runtime.register_op("listen", deno_core::op_sync(op_listen));
- runtime.register_op("close", deno_core::op_sync(op_close));
  runtime.register_op("accept", deno_core::op_async(op_accept));
- runtime.register_op("read", deno_core::op_async(op_read));
- runtime.register_op("write", deno_core::op_async(op_write));
  runtime.sync_ops_cache();
  runtime
 }
@@ -131,15 +143,6 @@ fn op_listen(
  Ok(rid)
 }
 
-fn op_close(
- state: &mut OpState,
- rid: ResourceId,
- _: (),
-) -> Result<(), AnyError> {
- log::debug!("close rid={}", rid);
- state.resource_table.close(rid).map(|_| ())
-}
-
 async fn op_accept(
  state: Rc<RefCell<OpState>>,
  rid: ResourceId,
@@ -153,30 +156,6 @@ async fn op_accept(
  Ok(rid)
 }
 
-async fn op_read(
- state: Rc<RefCell<OpState>>,
- rid: ResourceId,
- mut buf: ZeroCopyBuf,
-) -> Result<usize, AnyError> {
- log::debug!("read rid={}", rid);
-
- let stream = state.borrow().resource_table.get::<TcpStream>(rid)?;
- let nread = stream.read(&mut buf).await?;
- Ok(nread)
-}
-
-async fn op_write(
- state: Rc<RefCell<OpState>>,
- rid: ResourceId,
- buf: ZeroCopyBuf,
-) -> Result<usize, AnyError> {
- log::debug!("write rid={}", rid);
-
- let stream = state.borrow().resource_table.get::<TcpStream>(rid)?;
- let nwritten = stream.write(&buf).await?;
- Ok(nwritten)
-}
-
 fn main() {
  log::set_logger(&Logger).unwrap();
  log::set_max_level(

core/lib.deno_core.d.ts

@@ -45,6 +45,21 @@ declare namespace Deno {
  */
  function tryClose(rid: number): void;
 
+ /**
+ * Read from a (stream) resource that implements read()
+ */
+ function read(rid: number, buf: Uint8Array): Promise<number>;
+
+ /**
+ * Write to a (stream) resource that implements write()
+ */
+ function write(rid: number, buf: Uint8Array): Promise<number>;
+
+ /**
+ * Shutdown a resource
+ */
+ function shutdown(rid: number): Promise<void>;
+
  /** Get heap stats for current isolate/worker */
  function heapStats(): Record<string, number>;
 

core/lib.rs

@@ -86,6 +86,7 @@ pub use crate::ops_json::op_async_unref;
 pub use crate::ops_json::op_sync;
 pub use crate::ops_json::void_op_async;
 pub use crate::ops_json::void_op_sync;
+pub use crate::resources::AsyncResult;
 pub use crate::resources::Resource;
 pub use crate::resources::ResourceId;
 pub use crate::resources::ResourceTable;

core/ops_builtin.rs

@@ -1,6 +1,7 @@
 use crate::error::type_error;
 use crate::error::AnyError;
 use crate::include_js_files;
+use crate::op_async;
 use crate::op_sync;
 use crate::ops_metrics::OpMetrics;
 use crate::resources::ResourceId;
@@ -36,6 +37,10 @@ pub(crate) fn init_builtins() -> Extension {
  ("op_metrics", op_sync(op_metrics)),
  ("op_void_sync", void_op_sync()),
  ("op_void_async", void_op_async()),
+ // TODO(@AaronO): track IO metrics for builtin streams
+ ("op_read", op_async(op_read)),
+ ("op_write", op_async(op_write)),
+ ("op_shutdown", op_async(op_shutdown)),
  ])
  .build()
 }
@@ -170,3 +175,30 @@ pub fn op_metrics(
  let per_op = state.tracker.per_op();
  Ok((aggregate, per_op))
 }
+
+async fn op_read(
+ state: Rc<RefCell<OpState>>,
+ rid: ResourceId,
+ buf: ZeroCopyBuf,
+) -> Result<u32, AnyError> {
+ let resource = state.borrow().resource_table.get_any(rid)?;
+ resource.read(buf).await.map(|n| n as u32)
+}
+
+async fn op_write(
+ state: Rc<RefCell<OpState>>,
+ rid: ResourceId,
+ buf: ZeroCopyBuf,
+) -> Result<u32, AnyError> {
+ let resource = state.borrow().resource_table.get_any(rid)?;
+ resource.write(buf).await.map(|n| n as u32)
+}
+
+async fn op_shutdown(
+ state: Rc<RefCell<OpState>>,
+ rid: ResourceId,
+ _: (),
+) -> Result<(), AnyError> {
+ let resource = state.borrow().resource_table.get_any(rid)?;
+ resource.shutdown().await
+}

core/resources.rs

@@ -7,17 +7,25 @@
 // file descriptor (hence the different name).
 
 use crate::error::bad_resource_id;
+use crate::error::not_supported;
 use crate::error::AnyError;
+use crate::ZeroCopyBuf;
+use futures::Future;
 use std::any::type_name;
 use std::any::Any;
 use std::any::TypeId;
 use std::borrow::Cow;
 use std::collections::BTreeMap;
 use std::iter::Iterator;
+use std::pin::Pin;
 use std::rc::Rc;
 
+/// Returned by resource read/write/shutdown methods
+pub type AsyncResult<T> = Pin<Box<dyn Future<Output = Result<T, AnyError>>>>;
+
 /// All objects that can be store in the resource table should implement the
 /// `Resource` trait.
+/// TODO(@AaronO): investigate avoiding alloc on read/write/shutdown
 pub trait Resource: Any + 'static {
  /// Returns a string representation of the resource which is made available
  /// to JavaScript code through `op_resources`. The default implementation
@@ -27,6 +35,21 @@ pub trait Resource: Any + 'static {
  type_name::<Self>().into()
  }
 
+ /// Resources may implement `read()` to be a readable stream
+ fn read(self: Rc<Self>, _buf: ZeroCopyBuf) -> AsyncResult<usize> {
+ Box::pin(futures::future::err(not_supported()))
+ }
+
+ /// Resources may implement `write()` to be a writable stream
+ fn write(self: Rc<Self>, _buf: ZeroCopyBuf) -> AsyncResult<usize> {
+ Box::pin(futures::future::err(not_supported()))
+ }
+
+ /// Resources may implement `shutdown()` for graceful async shutdowns
+ fn shutdown(self: Rc<Self>) -> AsyncResult<()> {
+ Box::pin(futures::future::err(not_supported()))
+ }
+
  /// Resources may implement the `close()` trait method if they need to do
  /// resource specific clean-ups, such as cancelling pending futures, after a
  /// resource has been removed from the resource table.

ext/fetch/26_fetch.js

@@ -73,24 +73,6 @@
  return core.opAsync("op_fetch_send", rid);
  }
 
- /**
- * @param {number} rid
- * @param {Uint8Array} body
- * @returns {Promise<void>}
- */
- function opFetchRequestWrite(rid, body) {
- return core.opAsync("op_fetch_request_write", rid, body);
- }
-
- /**
- * @param {number} rid
- * @param {Uint8Array} body
- * @returns {Promise<number>}
- */
- function opFetchResponseRead(rid, body) {
- return core.opAsync("op_fetch_response_read", rid, body);
- }
-
  // A finalization registry to clean up underlying fetch resources that are GC'ed.
  const RESOURCE_REGISTRY = new FinalizationRegistry((rid) => {
  core.tryClose(rid);
@@ -120,7 +102,8 @@
  // This is the largest possible size for a single packet on a TLS
  // stream.
  const chunk = new Uint8Array(16 * 1024 + 256);
- const read = await opFetchResponseRead(
+ // TODO(@AaronO): switch to handle nulls if that's moved to core
+ const read = await core.read(
  responseBodyRid,
  chunk,
  );
@@ -260,7 +243,7 @@
  }
  try {
  await PromisePrototypeCatch(
- opFetchRequestWrite(requestBodyRid, value),
+ core.write(requestBodyRid, value),
  (err) => {
  if (terminator.aborted) return;
  throw err;