%% Copyright 2026 Benoit Chesneau
%%
%% Licensed under the Apache License, Version 2.0 (the "License");
%% you may not use this file except in compliance with the License.
%% You may obtain a copy of the License at
%%
%%     http://www.apache.org/licenses/LICENSE-2.0
%%
%% Unless required by applicable law or agreed to in writing, software
%% distributed under the License is distributed on an "AS IS" BASIS,
%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
%% See the License for the specific language governing permissions and
%% limitations under the License.

%%% @doc Zero-copy WSGI input buffer for streaming HTTP bodies.
%%%
%%% This module provides a buffer that can be written by Erlang and read
%%% by Python with zero-copy semantics. The buffer is suitable for use
%%% as wsgi.input in WSGI applications.
%%%
%%% == Usage ==
%%%
%%% ```
%%% %% Create a buffer (chunked encoding - unknown size)
%%% {ok, Buf} = py_buffer:new(),
%%%
%%% %% Or with known content length
%%% {ok, Buf} = py_buffer:new(1024),
%%%
%%% %% Write HTTP body chunks
%%% ok = py_buffer:write(Buf, <<"chunk1">>),
%%% ok = py_buffer:write(Buf, <<"chunk2">>),
%%%
%%% %% Signal end of data
%%% ok = py_buffer:close(Buf),
%%%
%%% %% Pass to Python WSGI - buffer is automatically converted
%%% py_context:call(Ctx, <<"myapp">>, <<"handle">>,
%%%                 [#{<<"wsgi.input">> => Buf}], #{}).
%%% '''
%%%
%%% On the Python side, the buffer provides a file-like interface:
%%%
%%% ```python
%%% def handle(environ):
%%%     body = environ['wsgi.input'].read()  # Blocks until data ready
%%%     # Or use readline(), readlines(), iteration
%%%     for line in environ['wsgi.input']:
%%%         process(line)
%%% '''
%%%
%%% @end
-module(py_buffer).

-export([
    new/0,
    new/1,
    write/2,
    close/1
]).

%% @doc Create a new buffer for chunked/streaming data.
%%
%% Use this when the content length is unknown (chunked transfer encoding).
%% The buffer will grow as needed.
%%
%% @returns {ok, BufferRef} | {error, Reason}
-spec new() -> {ok, reference()} | {error, term()}.
new() ->
    py_nif:py_buffer_create(undefined).

%% @doc Create a new buffer with known content length.
%%
%% Pre-allocates the buffer to the specified size for better performance.
%%
%% @param ContentLength Expected total size in bytes, or `undefined' for chunked
%% @returns {ok, BufferRef} | {error, Reason}
-spec new(non_neg_integer() | undefined) -> {ok, reference()} | {error, term()}.
new(undefined) ->
    py_nif:py_buffer_create(undefined);
new(ContentLength) when is_integer(ContentLength), ContentLength >= 0 ->
    py_nif:py_buffer_create(ContentLength).

%% @doc Write data to the buffer.
%%
%% Appends data to the buffer and signals any waiting Python readers.
%% This function is safe to call from multiple processes, but typically
%% only one process should write to a buffer.
%%
%% @param Ref Buffer reference from new/0 or new/1
%% @param Data Binary data to append
%% @returns ok | {error, Reason}
-spec write(reference(), binary()) -> ok | {error, term()}.
write(Ref, Data) when is_binary(Data) ->
    py_nif:py_buffer_write(Ref, Data).

%% @doc Close the buffer (signal end of data).
%%
%% Sets the EOF flag and wakes up any Python threads waiting for data.
%% After calling close, no more data can be written, and Python's read()
%% will return any remaining buffered data followed by empty bytes.
%%
%% @param Ref Buffer reference
%% @returns ok
-spec close(reference()) -> ok.
close(Ref) ->
    py_nif:py_buffer_close(Ref).