Skip to content

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).