feat(core): streams (#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 #12556

7 files changed, 108 insertions, 60 deletions

diff --git a/core/01_core.js b/core/01_core.js
index 9d4bab65d..75bfc884f 100644
--- a/core/01_core.js
+++ b/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,
diff --git a/core/examples/http_bench_json_ops.js b/core/examples/http_bench_json_ops.js
index ad36dd674..12d79a0ce 100644
--- a/core/examples/http_bench_json_ops.js
+++ b/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() {
diff --git a/core/examples/http_bench_json_ops.rs b/core/examples/http_bench_json_ops.rs
index 749f40485..6f14f558c 100644
--- a/core/examples/http_bench_json_ops.rs
+++ b/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(
diff --git a/core/lib.deno_core.d.ts b/core/lib.deno_core.d.ts
index 6db01df61..4a5d6433b 100644
--- a/core/lib.deno_core.d.ts
+++ b/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>;
 
diff --git a/core/lib.rs b/core/lib.rs
index abf702813..ceb2b89af 100644
--- a/core/lib.rs
+++ b/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;
diff --git a/core/ops_builtin.rs b/core/ops_builtin.rs
index d33565caf..a6cf82fe9 100644
--- a/core/ops_builtin.rs
+++ b/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
+}
diff --git a/core/resources.rs b/core/resources.rs
index c5e6684a4..33cabcad4 100644
--- a/core/resources.rs
+++ b/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.