Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-std

Source of release 0.7.1

0.7.1 / src / net / connection.lucb

#==============================================================================================
#
#   connection - A TCP connection
#
#   DESCRIPTION:
#       An owned TCP connection: connect, read, write, shutdown, socket options and readiness
#       waiting, and the line, text and byte reads a Luce program uses through `net.connect`.
#
#==============================================================================================

## Which direction to stop using on a connection. This does not close its owner.
pub enum ShutdownDirection as u8:
    read = 0
    write = 1
    both = 2

# mark: The connection ========================================================================

## One owned TCP connection implementing borrowed Reader and Writer interfaces.
## Zero is closed. Copying does not duplicate ownership; copies must not be
## independently closed. Synchronize calls on one owner. Luce sees a Connection as an
## object, made by `net.connect` or `Listener.accept_connection` and closed by `with`.
pub struct Connection: Reader, Writer:
    var socket: SocketHandle
    ## Whether the socket is marked against `SIGPIPE` (macOS); `write` marks it on first
    ## use, so a connection built any other way than `over` is guarded too.
    var guarded: bool
    ## Bytes `read_line` and `read_text` received beyond what they answered; `read`
    ## answers them first.
    var ahead: readahead.ReadAhead
    ## Whether `start_connect` left the connection in progress; `finish_connect` clears it.
    var connecting: bool

    ## Establish a TCP connection with an optional absolute deadline/cancellation.
    ## Connection setup is nonblocking internally; the returned socket is blocking
    ## unless nonblocking=true. Failure closes the newly acquired descriptor. DNS
    ## resolution is separate and is not covered by this connection deadline.
    pub static func connect(address: SocketAddress, deadline: Deadline = Deadline(), cancellation: sync.Cancellation*? = none, nonblocking: bool = false) -> Connection!:
        try check_operation(deadline, cancellation)
        var (acquired, connecting) = try open_connecting(address)
        errdefer acquired.destroy()
        let fd = try acquired.require()
        if connecting:
            _ = try wait_socket(fd, WaitInterest.write, deadline, cancellation)
            try check_operation(deadline, cancellation)
            try check_connected(fd)
        try check_operation(deadline, cancellation)
        try set_nonblocking(fd, nonblocking)
        acquired.nonblocking = nonblocking
        return Connection.from_socket(acquired)

    ## Begin a TCP connection without waiting for it, for an event loop: the socket is
    ## nonblocking and the connection may still be in progress. Wait for write readiness
    ## (a `Poller`, the loop's own wait), then call `finish_connect`, which tells whether
    ## it has completed and reports its failure. Failure here closes the new descriptor.
    pub static func start_connect(address: SocketAddress) -> Connection!:
        var (acquired, connecting) = try open_connecting(address)
        acquired.nonblocking = true
        var connection = Connection.from_socket(acquired)
        connection.connecting = connecting
        return connection

    ## Whether a connection begun by `start_connect` has completed, checked without
    ## waiting: false while it is in progress, true once connected (and for a connection
    ## made any other way). A failed connection reports its error (connection_refused,
    ## network_unreachable, timed_out, ...); close it then.
    pub func finish_connect() -> bool!:
        let descriptor = try self.socket.require()
        if not self.connecting:
            return true
        var entry: NativePoll[1]
        entry[0] = NativePoll(descriptor = descriptor, events = try poll_interest(WaitInterest.write))
        if (try wait_poll(entry, Deadline.at(0), none)) == 0:
            return false
        try check_connected(descriptor)
        self.connecting = false
        return true

    ## Take ownership of a socket the caller made (a `socketpair`, an inherited
    ## descriptor), including on failure. Set close-on-exec, preserving existing
    ## flags; this is not atomic with the caller's creation/fork/exec operations.
    ## A negative descriptor is rejected. The socket is marked so that a write after the peer closed fails
    ## instead of ending the process. Make the connection while the peer is still there:
    ## macOS refuses the mark on a socket whose peer has already gone, and a write on
    ## such a connection answers `closed` without sending.
    pub static func over(descriptor: platform.SocketDescriptor) -> Connection!:
        return Connection.from_socket(try SocketHandle.adopt(descriptor))

    static func from_socket(acquired: SocketHandle) -> Connection:
        var connection = Connection(socket = acquired, guarded = false)
        _ = connection.guard()
        return connection

    ## Query this connection's local IP endpoint, including its assigned port.
    pub func local_address() -> SocketAddress!:
        return try socket_address(try self.socket.require())

    ## Query the connected peer's IP endpoint; this is an address, not an identity.
    pub func peer_address() -> SocketAddress!:
        return try socket_address(try self.socket.require(), true)

    ## Stop one or both directions while retaining ownership. Shutting down writes
    ## sends EOF after queued TCP bytes, so the peer can still send its response.
    ## Use read shutdown only when input is no longer needed; treatment of queued
    ## input follows the host. Neither direction flushes user buffers; flush any
    ## io.BufferedWriter before shutting down writes.
    pub func shutdown(direction: ShutdownDirection = ShutdownDirection.both) -> !:
        let descriptor = try self.socket.require()
        if direction != ShutdownDirection.read and direction != ShutdownDirection.write and direction != ShutdownDirection.both:
            error(invalid_options, "unknown socket shutdown direction")
        var result = shutdown(descriptor, (i32)direction)
        while result < 0 and socket_errno() == socket_interrupted:
            result = shutdown(descriptor, (i32)direction)
        if result != 0:
            error(socket_error(socket_errno()), "the connection could not be shut down")

    ## Whether a write cannot raise `SIGPIPE`. Linux asks with every `send`
    ## (`MSG_NOSIGNAL`); macOS marks the socket once (`SO_NOSIGPIPE`), and refuses the mark
    ## with `EINVAL` on a socket whose peer has disconnected.
    func guard() -> bool:
        let descriptor = self.socket.value else return false
        if self.guarded:
            return true
        if not platform.macos:
            self.guarded = true
            return true
        else:
            var yes: i32 = 1
            var result = setsockopt(descriptor, socket_level, no_sigpipe_option, &yes, 4)
            while result < 0 and socket_errno() == socket_interrupted:
                result = setsockopt(descriptor, socket_level, no_sigpipe_option, &yes, 4)
            if result == 0:
                self.guarded = true
            return self.guarded

    ## Send some bytes, retrying interruption. Use io.write_all for a complete
    ## payload and its optional progress output to resume after a later failure.
    ## An empty input makes no syscall. A closed peer never raises SIGPIPE.
    pub func write(data: const u8[]) -> usize!:
        let descriptor = try self.socket.require()
        if data.length == 0:
            return 0
        if not self.guard():
            error(closed, "the connection closed")
        let count = data.length if data.length < transfer_limit else transfer_limit
        var sent = send(descriptor, data.data, count, send_flags)
        while sent < 0 and socket_errno() == socket_interrupted:
            sent = send(descriptor, data.data, count, send_flags)
        if sent < 0:
            error(socket_error(socket_errno()), "the connection could not send data")
        if sent == 0:
            error(io.no_progress, "the connection made no write progress")
        return (usize)sent

    ## Receive some bytes. For nonempty storage, zero is peer EOF; empty storage
    ## returns zero without probing the peer. This call does not fill the buffer.
    pub func read(buffer: u8[]) -> usize!:
        if self.ahead.count() > 0:
            _ = try self.socket.require()
            return self.ahead.take(buffer)
        return try self.receive(buffer)

    ## One receive from the socket itself, under the bytes read ahead.
    func receive(buffer: u8[]) -> usize!:
        let descriptor = try self.socket.require()
        if buffer.length == 0:
            return 0
        let count = buffer.length if buffer.length < transfer_limit else transfer_limit
        var received = recv(descriptor, buffer.data, count, 0)
        while received < 0 and socket_errno() == socket_interrupted:
            received = recv(descriptor, buffer.data, count, 0)
        if received < 0:
            error(socket_error(socket_errno()), "the connection could not receive data")
        return (usize)received

    # mark: Lines, text and bytes ============================================================

    ## The next line without its `\n` or `\r\n`; at the end of the stream the unfinished
    ## last line, and none after it. A line that is not UTF-8 is invalid_text.
    pub func read_line() -> str?!:
        var source = Received(connection = &self)
        return try self.ahead.line(&source)

    ## What arrives next, up to `maximum` bytes, waiting only while nothing has; empty when
    ## the peer has finished sending. The view lasts until the next read.
    pub func read_bytes(maximum: i64 = 65536) -> const u8[]!:
        if maximum < 1:
            error(invalid_options, "a read needs a positive maximum")
        var source = Received(connection = &self)
        return try self.ahead.bytes(&source, (usize)maximum, false)

    ## What arrives next as text, as read_bytes reads it, ending on a whole character; a
    ## character cut in two waits for the next read. Text that is not UTF-8 is invalid_text.
    pub func read_text(maximum: i64 = 65536) -> str!:
        if maximum < 1:
            error(invalid_options, "a read needs a positive maximum")
        var source = Received(connection = &self)
        return try self.ahead.text(&source, (usize)maximum, false)

    ## Send all of `data`.
    pub func write_bytes(data: const u8[]) -> !:
        try io.write_all(&self, data)

    ## Send all of `text`.
    pub func write_text(text: str) -> !:
        try io.write_all(&self, text.bytes)

    ## Disable Nagle coalescing when enabled. This is a latency policy, not a
    ## delivery guarantee; writes may still be buffered by the OS or network.
    pub func set_no_delay(enabled: bool) -> !:
        try set_socket_integer(try self.socket.require(), 6, 1, 1 if enabled else 0)

    ## Whether TCP no-delay (Nagle off) is set.
    pub func no_delay() -> bool!:
        return try get_socket_integer(try self.socket.require(), 6, 1) != 0

    ## Enable OS TCP keepalive probes. Timing and retry defaults remain host
    ## policy; keepalive does not provide an application operation deadline.
    pub func set_keepalive(enabled: bool) -> !:
        try set_socket_integer(try self.socket.require(), socket_level, keepalive_option, 1 if enabled else 0)

    ## Whether keepalive probing is enabled.
    pub func keepalive() -> bool!:
        return try get_socket_integer(try self.socket.require(), socket_level, keepalive_option) != 0

    ## Wait for advisory readiness without allocating. Expiration reports timed_out;
    ## cancellation reports cancelled. Use nonblocking I/O after readiness because
    ## another user can consume it. The socket remains borrowed and open.
    pub func wait(interest: WaitInterest = WaitInterest.read, deadline: Deadline = Deadline(), cancellation: sync.Cancellation*? = none) -> Readiness!:
        return try wait_socket(try self.socket.require(), interest, deadline, cancellation)

    ## Change O_NONBLOCK without changing other status flags. Descriptor aliases
    ## share this setting; synchronize changes with all users of this socket.
    pub func set_nonblocking(enabled: bool) -> !:
        try set_nonblocking(try self.socket.require(), enabled)
        self.socket.nonblocking = enabled

    ## Whether the socket is in nonblocking mode.
    pub func is_nonblocking() -> bool!:
        if platform.windows:
            _ = try self.socket.require()
            return self.socket.nonblocking
        else:
            return (try socket_status_flags(try self.socket.require()) & nonblocking_flag) != 0

    ## Request kernel buffering in bytes, not a guaranteed transfer size. The OS
    ## may cap or round the request; receive_buffer returns its reported setting.
    pub func set_receive_buffer(bytes: i32) -> !:
        try set_socket_buffer(try self.socket.require(), receive_buffer_option, bytes)

    ## The receive buffer size in bytes.
    pub func receive_buffer() -> i32!:
        return try get_socket_integer(try self.socket.require(), socket_level, receive_buffer_option)

    ## Request kernel buffering in bytes. Linux reports a doubled bookkeeping
    ## size; both hosts may adjust the request. This does not change user buffers.
    pub func set_send_buffer(bytes: i32) -> !:
        try set_socket_buffer(try self.socket.require(), send_buffer_option, bytes)

    ## The send buffer size in bytes.
    pub func send_buffer() -> i32!:
        return try get_socket_integer(try self.socket.require(), socket_level, send_buffer_option)

    ## Borrow the descriptor; the caller must not close it or retain it past this owner.
    pub func descriptor() -> platform.SocketDescriptor?:
        return self.socket.value

    ## Consume ownership before the OS call. Repeated close is safe even after failure.
    pub func close() -> !:
        self.ahead.release()
        try self.socket.close()

    ## Best-effort cleanup for unwinding; use close to observe delayed errors.
    pub func destroy():
        self.ahead.release()
        self.socket.destroy()

## A new nonblocking stream socket for `address` with its connect issued: the socket, and
## whether the connection is still in progress. Failure closes the socket.
func open_connecting(address: SocketAddress) -> (SocketHandle, bool)!:
    var raw: NativeAddress
    let length = try address.write_native(&raw)
    var acquired = try SocketHandle.create(stream, address.ip.kind)
    errdefer acquired.destroy()
    let fd = try acquired.require()
    if address.ip.kind == IpVersion.ipv6:
        try set_socket_integer(fd, ipv6_level, ipv6_only_option, 0)
    try set_nonblocking(fd, true)
    if socket_connect(fd, &raw, length) == 0:
        return (acquired, false)
    let number = socket_errno()
    let in_progress = 10035 if platform.windows else (36 if platform.macos else 115)
    let already_pending = 10037 if platform.windows else (37 if platform.macos else 114)
    if number != in_progress and number != already_pending and number != socket_interrupted:
        error(socket_error(number), "the connection could not reach its peer")
    return (acquired, true)

## The outcome of a connection that was in progress until its socket became writable: its
## pending error (`SO_ERROR`), if any.
func check_connected(descriptor: platform.SocketDescriptor) -> !:
    let pending_error = try get_socket_integer(descriptor, socket_level, 4103 if platform.macos or platform.windows else 4)
    if pending_error != 0:
        error(socket_error(pending_error), "the pending connection failed")

## The socket under a connection's read-ahead bytes.
struct Received: Reader:
    var connection: Connection*

    func read(buffer: u8[]) -> usize!:
        return try self.connection.receive(buffer)