// Copyright 2024 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.fdomain;

// Result from a socket write operation.
type WriteSocketError = struct {
    error Error;
    wrote uint64;
};

// Socket disposition.
type SocketDisposition = flexible enum {
    NO_CHANGE = 0;
    WRITE_ENABLED = 1;
    WRITE_DISABLED = 2;
};

// Socket type.
type SocketType = flexible enum {
    STREAM = 0;
    DATAGRAM = 1;
};

// Data resulting from reading a socket.
type SocketData = struct {
    data vector<uint8>;
    is_datagram bool;
};

// FDomain operations on sockets
@no_resource
open protocol Socket {
    // Create a new socket in this FDomain and return both its ends.
    flexible CreateSocket(struct {
        options SocketType;
        handles array<NewHandleId, 2>;
    }) -> () error Error;

    // Set the disposition of a given socket.
    flexible SetSocketDisposition(struct {
        handle HandleId;
        disposition SocketDisposition;
        disposition_peer SocketDisposition;
    }) -> () error Error;

    // Read data from a socket. This method will fail if the socket is currently being read
    // asynchronously.
    flexible ReadSocket(struct {
        handle HandleId;
        max_bytes uint64;
    }) -> (SocketData) error Error;

    // Write to a socket. This will attempt to write all the data passed, and
    // will block and retry whenever it is safe (e.g. it should never return
    // SHOULD_WAIT). The `WriteSocketError` contains a `wrote` parameter to
    // indicate if some bytes were written successfully before the failure
    // occurred.
    flexible WriteSocket(struct {
        handle HandleId;
        data vector<uint8>;
    }) -> (struct {
        wrote uint64;
    }) error WriteSocketError;

    // Starts reading from the given socket. Data is returned via the `SocketStreamingData` event. That
    // event will occur repeatedly until `ReadSocketStreamingStop` is called for the same handle or the
    // event indicates the handle is closed.
    flexible ReadSocketStreamingStart(struct {
        handle HandleId;
    }) -> () error Error;

    // Stop asynchronous reading from the given socket.
    flexible ReadSocketStreamingStop(struct {
        handle HandleId;
    }) -> () error Error;

    // Data read asynchronously from a socket.
    flexible -> OnSocketStreamingData(struct {
        handle HandleId;
        socket_message flexible union {
            1: data SocketData;
            2: stopped AioStopped;
        };
    });
};