mem.c

Go to the documentation of this file.

/*
 *   This program is free software; you can redistribute it and/or modify
 *   it under the terms of the GNU General Public License as published by
 *   the Free Software Foundation; either version 2 of the License, or (at
 *   your option) any later version.
 *
 *   This program is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with this program; if not, write to the Free Software
 *   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
 */
 
/**
 * $Id: 2ae7ff6ef1efab7e38ad4b2d2e418a6349f8d258 $
 * @file lib/bio/mem.c
 * @brief BIO abstractions for memory buffers
 *
 * @copyright 2024 Network RADIUS SAS (legal@networkradius.com)
 */
 
#include <freeradius-devel/bio/bio_priv.h>
#include <freeradius-devel/bio/null.h>
#include <freeradius-devel/bio/buf.h>
 
#include <freeradius-devel/bio/mem.h>
 
typedef enum : uint8_t {
        FR_BIO_MEM_INVALID = 0,
        FR_BIO_MEM_SOURCE,      /* the application writes to it, something else reads */
        FR_BIO_MEM_SINK,        /* something else writes to it, the application reads */
        FR_BIO_MEM_VERIFY,      /* verification only, with no buffers */
        FR_BIO_MEM_BUFFER,      /* we manage local buffers */
} fr_bio_mem_type_t;
 
/** The memory buffer bio
 *
 *  It is used to buffer reads / writes to a streaming socket.
 */
typedef struct fr_bio_mem_s {
        FR_BIO_COMMON;
 
        fr_bio_mem_type_t       type;   //!< source, sink, etc.
 
        fr_bio_verify_t verify;         //!< verify data to see if we have a packet.
        void            *verify_ctx;    //!< verify context
 
        fr_bio_buf_t    read_buffer;    //!< buffering for reads
        fr_bio_buf_t    write_buffer;   //!< buffering for writes
} fr_bio_mem_t;
 
static ssize_t fr_bio_mem_write_buffer(fr_bio_t *bio, void *packet_ctx, void const *buffer, size_t size);
 
static int     fr_bio_mem_call_verify(fr_bio_t *bio, void *packet_ctx, size_t *size) CC_HINT(nonnull(1,3));
 
/** At EOF, read data from the buffer until it is empty.
 *
 *  When "next" bio returns EOF, there may still be pending data in the memory buffer.  Return that until it's
 *  empty, and then EOF from then on.
 */
static ssize_t fr_bio_mem_read_eof(fr_bio_t *bio, UNUSED void *packet_ctx, void *buffer, size_t size)
{
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
 
        /*
         *      No more data: return EOF from now on.
         */
        if (fr_bio_buf_used(&my->read_buffer) == 0) {
 
                /*
                 *      Don't call our EOF function.  But do tell the other BIOs that we're at EOF.
                 */
                my->priv_cb.eof = NULL;
                fr_bio_eof(&my->bio);
                return 0;
        }
 
        /*
         *      Return whatever data we have available.  One the buffer is empty, the next read will get EOF.
         */
        return fr_bio_buf_read(&my->read_buffer, buffer, size);
}
 
static int fr_bio_mem_eof(fr_bio_t *bio)
{
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
 
        /*
         *      Nothing more for us to read, tell fr_bio_eof() that it can continue with poking other BIOs.
         */
        if (fr_bio_buf_used(&my->read_buffer) == 0) {
                return 1;
        }
 
        my->bio.read = fr_bio_mem_read_eof;
 
        return 0;
}
 
/** Read from a memory BIO
 *
 *  This bio reads as much data as possible into the memory buffer.  On the theory that a few memcpy() or
 *  memmove() calls are much cheaper than a system call.
 *
 *  If the read buffer has enough data to satisfy the read, then it is returned.
 *
 *  Otherwise the next bio is called to re-fill the buffer.  The next read call will try to get as much data
 *  as possible into the buffer, even if that results in reading more than "size" bytes.
 *
 *  Once the next read has been done, then the data from the buffer is returned, even if it is less than
 *  "size".
 */
static ssize_t fr_bio_mem_read(fr_bio_t *bio, void *packet_ctx, void *buffer, size_t size)
{
        ssize_t rcode;
        size_t used, room;
        uint8_t *p;
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
        fr_bio_t *next;
 
        /*
         *      We can satisfy the read from the memory buffer: do so.
         */
        used = fr_bio_buf_used(&my->read_buffer);
        if (size <= used) {
                return fr_bio_buf_read(&my->read_buffer, buffer, size);
        }
 
        /*
         *      There must be a next bio.
         */
        next = fr_bio_next(&my->bio);
        fr_assert(next != NULL);
 
        /*
         *      If there's no room to store more data in the buffer.  Just return whatever data we have in the
         *      buffer.
         */
        room = fr_bio_buf_write_room(&my->read_buffer);
        if (!room) return fr_bio_buf_read(&my->read_buffer, buffer, size);
 
        /*
         *      We try to fill the buffer as much as possible from the network, even if that means reading
         *      more than "size" amount of data.
         */
        p = fr_bio_buf_write_reserve(&my->read_buffer, room);
        fr_assert(p != NULL);   /* otherwise room would be zero */
 
        rcode = next->read(next, packet_ctx, p, room);
        if (rcode < 0) return rcode;
 
        /*
         *      Ensure that whatever data we have read (zero or more) is marked as "used" in the buffer, and
         *      then return whatever data is available back to the caller.
         */
        (void) fr_bio_buf_write_alloc(&my->read_buffer, (size_t) rcode);
 
        return fr_bio_buf_read(&my->read_buffer, buffer, size);
}
 
/** See is there's a full packet in the buffer.
 *
 */
static ssize_t fr_bio_mem_read_packet(fr_bio_t *bio, void *packet_ctx, void *buffer, size_t size)
{
        ssize_t rcode;
        size_t want;
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
 
        /*
         *      See if there are valid packets in the buffer.
         */
        rcode = fr_bio_mem_call_verify(bio, packet_ctx, &want);
        if (rcode < 0) return fr_bio_error(VERIFY);
 
        /*
         *      No valid packet.
         */
        if (rcode == 0) return 0;
 
        /*
         *      There's at least one valid packet, return it.
         *
         *      Not enough room isn't a fatal error.  The caller should check how much room is needed by
         *      calling fr_bio_mem_call_verify(), and retry.
         *
         *      But in general, the caller should make sure that the output buffer has enough room for at
         *      least one packet.  The verify() function should also ensure that the packet is no larger than
         *      our application maximum, even if the protocol allows for it to be larger.
         */
        if (want > size) return fr_bio_error(BUFFER_TOO_SMALL);
 
        return fr_bio_buf_read(&my->read_buffer, buffer, want);
}
 
/** Return data only if we have a complete packet.
 *
 */
static ssize_t fr_bio_mem_read_verify_stream(fr_bio_t *bio, void *packet_ctx, void *buffer, size_t size)
{
        ssize_t rcode;
        size_t used, room;
        uint8_t *p;
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
        fr_bio_t *next;
 
        /*
         *      We may be able to satisfy the read from the memory buffer.
         */
        used = fr_bio_buf_used(&my->read_buffer);
        if (used) {
                rcode = fr_bio_mem_read_packet(bio, packet_ctx, buffer, size);
 
                /*
                 *      A packet, or an error.  Zero means that the buffer holds only part of a packet, and
                 *      we need to read more data before we can return anything.
                 */
                if (rcode != 0) return rcode;
        }
 
        /*
         *      There must be a next bio.
         */
        next = fr_bio_next(&my->bio);
        fr_assert(next != NULL);
 
        /*
         *      If there's no room to store more data in the buffer, try to make some room.
         */
        room = fr_bio_buf_write_room(&my->read_buffer);
        if (!room) {
                room = fr_bio_buf_make_room(&my->read_buffer);
 
                /*
                 *      We've tried to make room and failed.  Which means that the buffer is full, AND there
                 *      still isn't a complete packet in the buffer.  This is therefore an error.  The
                 *      application has not supplied us with enough read_buffer space to store a complete
                 *      packet.
                 *
                 *      @todo - allow the application to increase the size of the buffer.
                 */
                if (!room) return fr_bio_error(BUFFER_FULL);
        }
 
        /*
         *      We try to fill the buffer as much as possible from the network.  The theory is that a few
         *      extra memcpy() or memmove()s are cheaper than a system call for reading each packet.
         */
        p = fr_bio_buf_write_reserve(&my->read_buffer, room);
        fr_assert(p != NULL);   /* otherwise room would be zero */
 
        rcode = next->read(next, packet_ctx, p, room);
        if (rcode <= 0) return rcode;
 
        /*
         *      The next bio returned some data.  Bump up what's used in the buffer, and see if it's a valid packet.
         */
        (void) fr_bio_buf_write_alloc(&my->read_buffer, (size_t) rcode);
        return fr_bio_mem_read_packet(bio, packet_ctx, buffer, size);
}
 
/** Return data only if we have a complete packet.
 *
 */
static ssize_t fr_bio_mem_read_verify_datagram(fr_bio_t *bio, void *packet_ctx, void *buffer, size_t size)
{
        ssize_t rcode;
        size_t want;
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
        fr_bio_t *next;
 
        /*
         *      There must be a next bio.
         */
        next = fr_bio_next(&my->bio);
        fr_assert(next != NULL);
 
        rcode = next->read(next, packet_ctx, buffer, size);
        if (rcode <= 0) return rcode;
 
        /*
         *      We have some data.
         */
        want = rcode;
 
        /*
         *      It's a datagram socket, there can only be one packet in the buffer.
         *
         *      @todo - if we're allowed more than one packet in the buffer, we should just call
         *      fr_bio_mem_read_verify(), or this function should call fr_bio_mem_call_verify().
         */
        switch (my->verify((fr_bio_t *) my, my->verify_ctx, packet_ctx, buffer, &want)) {
                /*
                 *      The data in the buffer is exactly a packet.  Return that.
                 *
                 *      @todo - if there are multiple packets, return the total size of packets?
                 */
        case FR_BIO_VERIFY_OK:
                fr_assert(want <= (size_t) rcode);
                return want;
 
                /*
                 *      The data in the buffer doesn't make up a complete packet, discard it.  The
                 *      called verify function should take care of logging.
                 */
        case FR_BIO_VERIFY_WANT_MORE:
                return 0;
 
        case FR_BIO_VERIFY_DISCARD:
                return 0;
 
                /*
                 *      The verification routine told us to close the socket, so we do that.
                 *
                 *      This is typically because the application-layer got something which is invalid.
                 */
        case FR_BIO_VERIFY_ERROR_CLOSE:
                break;
        }
 
        (void) fr_bio_shutdown_discard(bio); /* the buffered data is what failed */
        return fr_bio_error(VERIFY);
}
 
 
/** Pass writes to the next BIO
 *
 *  For speed, we try to bypass the memory buffer and write directly to the next bio.  However, if the next
 *  bio returns EWOULDBLOCK, we write the data to the memory buffer, even if it is partial data.
 */
static ssize_t fr_bio_mem_write_next(fr_bio_t *bio, void *packet_ctx, void const *buffer, size_t size)
{
        int error;
        ssize_t rcode;
        size_t room, leftover;
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
        fr_bio_t *next;
 
        /*
         *      We can't call the next bio if there's still cached data to flush.
         *
         *      There must be a next bio.
         */
        fr_assert(fr_bio_buf_used(&my->write_buffer) == 0);
 
        next = fr_bio_next(&my->bio);
        fr_assert(next != NULL);
 
        rcode = next->write(next, packet_ctx, buffer, size);
        if (rcode < 0) return rcode;
 
        /*
         *      The next bio may write all of the data.  If so, we return that,
         */
        if ((size_t) rcode == size) return rcode;
 
        /*
         *      We were flushing the BIO, return however much data we managed to write.
         *
         *      Note that flushes should never block.
         */
        if (!buffer) return rcode;
 
        /*
         *      Tell previous BIOs in the chain that they are blocked.
         */
        error = fr_bio_write_blocked(bio);
        if (error < 0) return error;
 
        /*
         *      We had WOULD BLOCK, or wrote partial bytes.  Save the data to the memory buffer, and ensure
         *      that future writes are ordered.  i.e. they write to the memory buffer before writing to the
         *      next bio.
         */
        bio->write = fr_bio_mem_write_buffer;
 
        /*
         *      Clamp the write to however much data is available in the buffer.
         */
        leftover = size - rcode;
        room = fr_bio_buf_write_room(&my->write_buffer);
 
        /*
         *      If we have "used == 0" above, then we must also have "room > 0".
         */
        fr_assert(room > 0);
 
        if (room < leftover) leftover = room;
 
        /*
         *      Since we've clamped the write, this call can never fail.
         */
        (void) fr_bio_buf_write(&my->write_buffer, ((uint8_t const *) buffer) + rcode, leftover);
 
        /*
         *      Some of the data base been written to the next bio, and some to our cache.  The caller has to
         *      ensure that the first subsequent write will send over the rest of the data.
         *
         *      However, we tell the caller that we wrote the entire packet.  Because we are now responsible
         *      for writing the remaining bytes.
         */
        return size;
}
 
/** Flush the memory buffer.
 *
 *  Note that this can't be used for unconnected FD sockets, as we
 *  don't have a packet_ctx to pass to the next write function!
 */
static ssize_t fr_bio_mem_write_flush(fr_bio_mem_t *my, size_t size)
{
        ssize_t rcode;
        size_t used;
        fr_bio_t *next;
 
        /*
         *      Nothing to flush, don't do any writes.
         *
         *      Instead, set the write function to write next, where data will be sent directly to the next
         *      bio, and will bypass the write buffer.
         */
        used = fr_bio_buf_used(&my->write_buffer);
        if (!used) {
                my->bio.write = fr_bio_mem_write_next;
                return 0;
        }
 
        next = fr_bio_next(&my->bio);
        fr_assert(next != NULL);
 
        /*
         *      Clamp the amount of data written.  If the caller wants to write everything, it should
         *      pass SIZE_MAX.
         */
        if (used < size) size = used;
 
        /*
         *      Flush the buffer to the next bio in line.  That function will write as much data as possible,
         *      but may return a partial write.
         */
        rcode = next->write(next, NULL, my->write_buffer.read, size);
 
        /*
         *      No write, or a "would block" error, that's a "would block" error.
         */
        if ((rcode == 0) || (rcode == fr_bio_error(IO_WOULD_BLOCK))) return fr_bio_error(IO_WOULD_BLOCK);
 
        if (rcode < 0) return rcode;
 
        /*
         *      Tell the buffer that we've read a certain amount of data from it.
         */
        (void) fr_bio_buf_read(&my->write_buffer, NULL, (size_t) rcode);
 
        /*
         *      We haven't emptied the buffer, any further IO is blocked.
         */
        if ((size_t) rcode < used) return fr_bio_error(IO_WOULD_BLOCK);
 
        /*
         *      We've flushed all of the buffer.  Revert back to "pass through" writing.
         */
        fr_assert(fr_bio_buf_used(&my->write_buffer) == 0);
        my->bio.write = fr_bio_mem_write_next;
        return rcode;
}
 
/** Write to the memory buffer.
 *
 *  The special buffer pointer of NULL means flush().  On flush, we call next->read(), and if that succeeds,
 *  go back to "pass through" mode for the buffers.
 *
 *  This can only be called for streams, not for datagrams.
 */
static ssize_t fr_bio_mem_write_buffer(fr_bio_t *bio, UNUSED void *packet_ctx, void const *buffer, size_t size)
{
        size_t room;
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
 
        /*
         *      Flush the output buffer.
         */
        if (unlikely(!buffer)) return fr_bio_mem_write_flush(my, size);
 
        /*
         *      Clamp the write to however much data is available in the buffer.
         */
        room = fr_bio_buf_write_room(&my->write_buffer);
 
        /*
         *      The buffer is full, we can't write anything.
         */
        if (!room) return fr_bio_error(IO_WOULD_BLOCK);
 
        /*
         *      If we're asked to write more bytes than are available in the buffer, then tell the caller that
         *      writes are now blocked, and we can't write any more data.
         *
         *      Return an WOULD_BLOCK error instead of breaking our promise by writing part of the data,
         *      instead of accepting a full application write.
         */
        if (room < size) {
                int rcode;
 
                rcode = fr_bio_write_blocked(bio);
                if (rcode < 0) return rcode;
 
                return fr_bio_error(IO_WOULD_BLOCK);
        }
 
        /*
         *      As we have clamped the write, we know that this call must succeed.
         */
        (void) fr_bio_buf_write(&my->write_buffer, buffer, size);
 
        /*
         *      If we've filled the buffer, tell the caller that writes are now blocked, and we can't write
         *      any more data.  However, we still return the amount of data we wrote.
         */
        if (room == size) {
                int rcode;
 
                rcode = fr_bio_write_blocked(bio);
                if (rcode < 0) return rcode;
        }
 
        return size;
}
 
/** Peek at the data in the read buffer
 *
 *  Peeking at the data allows us to avoid many memory copies.
 */
uint8_t const *fr_bio_mem_read_peek(fr_bio_t *bio, size_t *size)
{
        size_t used;
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
 
        used = fr_bio_buf_used(&my->read_buffer);
 
        if (!used) return NULL;
 
        *size = used;
        return my->read_buffer.read;
}
 
/** Discard data from the read buffer.
 *
 *  Discarding allows the caller to silently omit packets, so that
 *  they are not passed up to previous bios.
 */
void fr_bio_mem_read_discard(fr_bio_t *bio, size_t size)
{
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
 
        (void) fr_bio_buf_read(&my->read_buffer, NULL, size);
}
 
/** Verify that a packet is OK.
 *
 *  @todo - have this as a parameter to the read routines, so that they only return complete packets?
 *
 *  @param      bio     the #fr_bio_mem_t
 *  @param      packet_ctx the packet ctx
 *  @param[out] size    how big the verified packet is
 *  @return
 *      - <0 for a fatal error
 *      - 0 for "we have a partial packet", the size to read is in *size
 *      - 1 for "we have at least one good packet", the size of it is in *size
 */
static int fr_bio_mem_call_verify(fr_bio_t *bio, void *packet_ctx, size_t *size)
{
        uint8_t *packet, *end;
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
 
        packet = my->read_buffer.read;
        end = my->read_buffer.write;
 
        while (packet < end) {
                size_t want;
#ifndef NDEBUG
                size_t used;
 
                used = end - packet;
#endif
 
                want = end - packet;
 
                switch (my->verify((fr_bio_t *) my, my->verify_ctx, packet_ctx, packet, &want)) {
                        /*
                         *      The data in the buffer is exactly a packet.  Return that.
                         *
                         *      @todo - if there are multiple packets, return the total size of packets?
                         */
                case FR_BIO_VERIFY_OK:
                        fr_assert(want <= used);
                        *size = want;
                        return 1;
 
                        /*
                         *      The packet needs more data.  Return how much data we need for one packet.
                         */
                case FR_BIO_VERIFY_WANT_MORE:
                        fr_assert(want > used);
                        *size = want;
                        return 0;
 
                case FR_BIO_VERIFY_DISCARD:
                        /*
                         *      We don't call fr_bio_buf_read(), because that will move the memory around, and
                         *      we want to avoid that if at all possible.
                         */
                        fr_assert(want <= used);
                        fr_assert(packet == my->read_buffer.read);
                        packet = my->read_buffer.read += want;
                        continue;
 
                        /*
                         *      Some kind of fatal validation error.
                         */
                case FR_BIO_VERIFY_ERROR_CLOSE:
                        (void) fr_bio_shutdown_discard(bio); /* the buffered data is what failed */
                        return -1;
                }
        }
 
        /*
         *      We haven't returned a full packet, partial packet, or error.  We must have discarded
         *      everything in the buffer.
         */
        if (my->read_buffer.read == my->read_buffer.write) fr_bio_buf_reset(&my->read_buffer);
 
        *size = 0;
        return 0;
}
 
/** Allocate a memory buffer bio for either reading or writing.
 *
 *  Frees "my" on failure, so that we don't need to put that in all of the callers.
 */
static bool fr_bio_mem_buf_alloc(fr_bio_mem_t *my, fr_bio_buf_t *buf, size_t size)
{
        if (size < 1024) size = 1024;
        if (size > (1 << 20)) size = 1 << 20;
 
        if (fr_bio_buf_alloc(my, buf, size) < 0) {
                talloc_free(my);
                return false;
        }
 
        return true;
}
 
/** Allocate a memory buffer bio
 *
 *  The "read buffer" will cache reads from the next bio in the chain.  If the next bio returns more data than
 *  the caller asked for, the extra data is cached in the read buffer.
 *
 *  The "write buffer" will buffer writes to the next bio in the chain.  If the caller writes more data than
 *  the next bio can process, the extra data is cached in the write buffer.
 *
 *  When the bio is closed (or freed) any pending data in the buffers is lost.  The same happens if the next
 *  bio returns a fatal error.
 *
 *  At some point during a read, the next bio may return EOF.  When that happens, the caller should not rely
 *  on the next FD being readable or writable.  Instead, it should keep reading from the memory bio until it
 *  returns EOF.  See fr_bio_fd_eof() for details.
 *
 *  @param ctx          the talloc ctx
 *  @param read_size    size of the read buffer.  Must be 1024..2^20
 *  @param write_size   size of the write buffer.  Can be zero. If non-zero, must be 1024..2^20
 *  @param next         the next bio which will perform the underlying reads and writes.
 *      - NULL on error, memory allocation failed
 *      - !NULL the bio
 */
fr_bio_t *fr_bio_mem_alloc(TALLOC_CTX *ctx, size_t read_size, size_t write_size, fr_bio_t *next)
{
        fr_bio_mem_t *my;
 
        my = talloc_zero(ctx, fr_bio_mem_t);
        if (!my) return NULL;
 
        /*
         *      We can do 0-sized buffers for read, and the application should then set the verify function.
         */
        if (!read_size) {
                my->type = FR_BIO_MEM_VERIFY;
                my->bio.read = fr_bio_fail_read; /* can't read anything until the verify routine is put in place */
                my->bio.write = fr_bio_next_write;
 
                if (write_size > 0) {
                        talloc_free(my);
                        fr_strerror_const("Invalid write size.  If read size is zero, then write size must also be zero");
                        return NULL;
                }
 
        } else {
                /*
                 *      We have a read buffer, and potentially a write buffer.
                 */
                my->type = FR_BIO_MEM_BUFFER;
 
                if (!fr_bio_mem_buf_alloc(my, &my->read_buffer, read_size)) {
                oom:
                        fr_strerror_const("Out of memory");
                        return NULL;
                }
                my->bio.read = fr_bio_mem_read;
 
                if (write_size) {
                        if (!fr_bio_mem_buf_alloc(my, &my->write_buffer, write_size)) goto oom;
 
                        /*
                         *     Default to passing writes straight through, but buffer them locally if the
                         *     write blocks.
                         *
                         *      We also only need to resume writes if we're buffering data.
                         */
                        my->bio.write = fr_bio_mem_write_next;
                        my->priv_cb.write_resume = fr_bio_mem_write_resume;
 
                } else {
                        my->bio.write = fr_bio_next_write;
                }
 
                /*
                 *      EOF and shutdown are needed if there's a read buffer, but not when the memory bio is
                 *      just doing packet verification/
                 */
                my->priv_cb.eof = fr_bio_mem_eof;
        }
 
        fr_bio_chain(&my->bio, next);
 
        talloc_set_destructor((fr_bio_t *) my, fr_bio_destructor); /* always use a common destructor */
        return (fr_bio_t *) my;
}
 
 
/** Allocate a memory buffer which sources data from the callers application into the bio system.
 *
 *  The caller writes data to the buffer, but never reads from it.  This bio will call the "next" bio to write
 *  the data. somewhere.
 */
fr_bio_t *fr_bio_mem_source_alloc(TALLOC_CTX *ctx, size_t write_size, fr_bio_t *next)
{
        fr_bio_mem_t *my;
 
        /*
         *      The caller has to state that the API is caching data.
         */
        if (!write_size) return NULL;
 
        my = talloc_zero(ctx, fr_bio_mem_t);
        if (!my) return NULL;
 
        if (!fr_bio_mem_buf_alloc(my, &my->write_buffer, write_size)) {
                return NULL;
        }
 
        my->type = FR_BIO_MEM_SOURCE;
        my->bio.read = fr_bio_fail_read; /* reading FROM this bio is not possible */
        my->bio.write = fr_bio_mem_write_next;
 
        /*
         *      @todo - have write pause / write resume callbacks?
         */
 
        fr_bio_chain(&my->bio, next);
 
        talloc_set_destructor((fr_bio_t *) my, fr_bio_destructor);
        return (fr_bio_t *) my;
}
 
/** Read from a buffer which a previous bio has filled.
 *
 *  This function is called by the application which wants to read from a sink.
 */
static ssize_t fr_bio_mem_read_buffer(fr_bio_t *bio, UNUSED void *packet_ctx, void *buffer, size_t size)
{
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
 
        return fr_bio_buf_read(&my->read_buffer, buffer, size);
}
 
/** Write to the read buffer.
 *
 *  This function is called by an upstream function which writes into our local buffer.
 */
static ssize_t fr_bio_mem_write_read_buffer(fr_bio_t *bio, UNUSED void *packet_ctx, void const *buffer, size_t size)
{
        size_t room;
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
 
        /*
         *      Clamp the write to however much data is available in the buffer.
         */
        room = fr_bio_buf_write_room(&my->read_buffer);
 
        /*
         *      The buffer is full.  We're now blocked.
         */
        if (!room) return fr_bio_error(IO_WOULD_BLOCK);
 
        if (room < size) size = room;
 
        /*
         *      As we have clamped the write, we know that this call must succeed.
         */
        return fr_bio_buf_write(&my->read_buffer, buffer, size);
}
 
/** Allocate a memory buffer which sinks data from a bio system into the callers application.
 *
 *  The caller reads data from this bio, but never writes to it.  Upstream BIOs will source the data.
 */
fr_bio_t *fr_bio_mem_sink_alloc(TALLOC_CTX *ctx, size_t read_size)
{
        fr_bio_mem_t *my;
 
        /*
         *      The caller has to state that the API is caching data.
         */
        if (!read_size) return NULL;
 
        my = talloc_zero(ctx, fr_bio_mem_t);
        if (!my) return NULL;
 
        if (!fr_bio_mem_buf_alloc(my, &my->read_buffer, read_size)) {
                return NULL;
        }
 
        my->type = FR_BIO_MEM_SINK;
        my->bio.read = fr_bio_mem_read_buffer;
        my->bio.write = fr_bio_mem_write_read_buffer; /* the upstream will write to our read buffer */
 
        talloc_set_destructor((fr_bio_t *) my, fr_bio_destructor); /* always use a common destructor */
        return (fr_bio_t *) my;
}
 
/** Set the verification function for memory bios.
 *
 *  It is possible to add a verification function.  It is not currently possible to remove one.
 *
 *  @param bio          the binary IO handler
 *  @param verify       the verification function
 *  @param verify_ctx   to pass to the verification function
 *  @param datagram     whether or not this bio is a datagram one.
 *  @return
 *      - <0 on error
 *      - 0 on success
 */
int fr_bio_mem_set_verify(fr_bio_t *bio, fr_bio_verify_t verify, void *verify_ctx, bool datagram)
{
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
 
        switch (my->type) {
        case FR_BIO_MEM_INVALID:
                fr_assert(0);
                return -1;
 
        case FR_BIO_MEM_SOURCE:
        case FR_BIO_MEM_SINK:
                fr_strerror_const("Cannot add verify to this memory BIO");
                return fr_bio_error(GENERIC);
 
        case FR_BIO_MEM_VERIFY:
                fr_assert(my->bio.write == fr_bio_next_write);
                if (!datagram) {
                        fr_strerror_const("Invalid memory BIO - we need a read buffer for verifying packets from a stream socket");
                        return -1;
                }
                FALL_THROUGH;
 
        case FR_BIO_MEM_BUFFER:
                break;
        }
 
        my->verify = verify;
        my->verify_ctx = verify_ctx;
 
        /*
         *      For reading datagrams, we just verify the packet in place.  This works both when we have local
         *      buffers, and when we are verifying packets in the application-supplied buffer.
         *
         *      For writing datagrams, then we cannot buffer individual datagrams.  We must write
         *      either all of the datagram out, or none of it.
         */
        if (datagram) {
                my->bio.read = fr_bio_mem_read_verify_datagram;
                my->bio.write = fr_bio_next_write;
 
                /*
                 *      Might as well free the memory for the write buffer.  It won't be used.
                 */
                if (my->write_buffer.start) {
                        talloc_free(my->write_buffer.start);
                        my->write_buffer = (fr_bio_buf_t) {};
                }
        } else {
                my->bio.read = fr_bio_mem_read_verify_stream;
                /* don't touch the write function or the write buffer. */
        }
 
        return 0;
}
 
/*
 *      There's no fr_bio_mem_write_blocked()
 */
 
/** See if we can resume writes to the memory bio.
 *
 *  Note that there is no equivalent fr_bio_mem_write_blocked(), as that function wouldn't do anything.
 *  Perhaps it could swap the write function to fr_bio_mem_write_buffer(), but the fr_bio_mem_write_next()
 *  function should automatically do that when the write to the next bio only writes part of the data,
 *  or if it returns fr_bio_error(IO_WOULD_BLOCK)
 */
int fr_bio_mem_write_resume(fr_bio_t *bio)
{
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
        ssize_t rcode;
 
        if (bio->write != fr_bio_mem_write_buffer) return 1;
 
        fr_assert(my->type == FR_BIO_MEM_BUFFER);
 
        /*
         *      Flush the buffer, and then reset the write routine if we were successful.
         */
        rcode = fr_bio_mem_write_flush(my, SIZE_MAX);
        if (rcode < 0) {
                /*
                 *      Still blocked, can't resume.
                 */
                if (rcode == fr_bio_error(IO_WOULD_BLOCK)) return 0;
 
                return rcode;
        }
 
        /*
         *      There's no EWOULDBLOCK, so we try to resume.
         */
        fr_assert((rcode == 0) || (fr_bio_buf_used(&my->write_buffer) == 0));
 
        /*
         *      Check for an application hook to check if we can resume writes.
         */
        if (!my->cb.write_resume) return 1;
 
        return my->cb.write_resume(bio);
}
 
/** Pause writes.
 *
 *  Calls to fr_bio_write() will write to the memory buffer, and not
 *  to the next bio.  You MUST call fr_bio_mem_write_resume() after
 *  this to flush any data.
 */
int fr_bio_mem_write_pause(fr_bio_t *bio)
{
        fr_bio_mem_t *my = talloc_get_type_abort(bio, fr_bio_mem_t);
 
        if (my->bio.write == fr_bio_mem_write_buffer) return 0;
 
        if (!my->bio.write || !fr_bio_buf_initialized(&my->write_buffer)) {
                fr_strerror_const("Cannot pause writes on a BIO with no write buffer");
                return fr_bio_error(GENERIC);
        }
 
        /*
         *      Sink only, can't pause.
         */
        if (my->bio.write == fr_bio_mem_write_read_buffer) return -1;
 
        my->bio.write = fr_bio_mem_write_buffer;
 
        return 0;
}