The network¶
import net adds endpoints that are transports, net.http(…), and
from net import * binds the constructors without it, http(…). They are read and written by
source, tap, target and sink like any other endpoint, and
constructing one sends nothing. Naming the module in the program's first
lines is how a program states that it may reach the network.
http(url) is Replayable: reading it sends one GET per evaluation and
decodes the response body, so source gives a Seq:
from net import *
source(http("https://api.example.com/birds"), Json)
Seq<Data>
websocket(url) is live: each message is one document, read as it arrives,
so reading it gives a Stream:
from net import *
tap(websocket("wss://events.example.com"), Json)
Stream<Data>
Writing an http endpoint sends one request per document, with the document
as its body, by the method given, "GET" unless written. The response is
read only for its status, and a status that is not a success is an evaluation
failure naming the URL:
from net import *
source(file("examples/io/sightings.jsonl"))
| target(http("https://api.example.com/report", method = "POST"), Json)
Step
tcp(host, port) is a TCP connection: its documents are separated as
their format separates them, one JSON value after another or one line at a
time.
Network bounds¶
A network read or write ends. A connection that is not made within 10
seconds is an evaluation failure naming the URL, or the host and port of a
tcp endpoint. An http response that sends nothing for 30 seconds is an
evaluation failure naming the URL, and so is a websocket handshake the
server answers nothing to for 30 seconds. timeout_ms sets the response
bound of one http endpoint, in milliseconds above 0:
from net import *
source(http("https://api.example.com/birds", timeout_ms = 5000), Json)
Seq<Data>
Once a websocket or tcp connection is open, tap waits for the next
document without limit, as any Stream does.
Without the import the endpoint constructors are not in scope:
source(http("https://api.example.com/birds"), Json)
check error[unknown-name]: `http` is declared in the module `io.net`: write `from net import http`
--> <expression>:1:8
|
1 | source(http("https://api.example.com/birds"), Json)
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A header is ordinary data in the program's text, so a request that needs credentials belongs in configuration, as an endpoint by id, and not in a program (endpoints by id). A document being rendered reaches no network (effects and what a host allows).