Marmos
v juptune
v asn1
v lang
v ast
v Classes
v Enums
v ir
v parser
v Enums
v Structs
v core
v crypto
v keyexchange
v memory
v data
v alphabet
v buffer
v json
v builder
v parser
v Enums
v Structs
v serialise
v Structs
v Templates
v pem
v Enums
v Structs

Structs Http1WriterBase

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
module juptune.http.v1;

struct Http1WriterBase(
    SocketT
)
{
    /++ STRUCTS ++/
    
    ///
    struct MessageState
    {
        /++ VARIABLES ++/
        
        ///
        BodyEncoding bodyEncoding;
        ///
        size_t contentLength;
        ///
        Http1Version httpVersion;
        ///
        bool isRequest;
        ///
        Http1MessageSummary summary;
    }
    
    /++ ALIASES ++/
    
    ///
    alias Machine = ;
    ///
    alias StateMachine = Machine.;
    /// Finishes the headers. 
    alias finishHeaders = ;
    /// Ditto. 
    alias finishTrailers = ;
    /// Writes a single header. 
    alias putHeader = ;
    /// Ditto. 
    alias putTrailer = ;
    
    /++ FUNCTIONS ++/
    
    ///
    Result bufferHeaderName(char[] name, const char[] buffered);
    ///
    Result bufferedWrite(void[] data);
    /// Finishes the body. 
    Result finishBody();
    ///
    Result finishHeadersImpl(bool trailers)();
    /// Acknowledges that the entire HTTP message has been written, and returns a summary 
    Result finishMessage(Http1MessageSummary summary);
    ///
    Result flush();
    ///
    Result processHeader(char[] name, char[] value);
    /// Writes body data. 
    Result putBody(void[] data);
    ///
    Result putBodyChunked(void[] data);
    ///
    Result putBodyContentLength(void[] data);
    ///
    Result putHeaderImpl(bool trailers)(char[] name, char[] value);
    /// Writes an entire request line. This will configure this writer to be a request writer for the remainder of the message, until finishMessage is called. 
    Result putRequestLine(char[] method, char[] path, Http1Version httpVersion);
    /// Writes an entire response line. This will configure this writer to be a response writer for the remainder of the message, until finishMessage is called. 
    Result putResponseLine(Http1Version httpVersion, uint statusCode, char[] reason);
    /// Writes the HTTP message stored within the provided result to the socket. 
    Result putResultResponse(Result result);
    
    /++ ENUMS ++/
    
    ///
    enum BodyEncoding
    {
        ///
        FAILSAFE, 
        ///
        hasContentLength = 1 << 0, 
        ///
        isChunked = 1 << 1, 
        ///
        hasTransferEncoding = 1 << 2
    }
    ///
    enum State
    {
        ///
        FAILSAFE, 
        ///
        startLine, 
        ///
        headers, 
        ///
        body, 
        ///
        trailers, 
        ///
        finalise
    }
    
    /++ VARIABLES ++/
    
    ///
    ubyte[] _buffer;
    ///
    Http1Config _config;
    ///
    MessageState _message;
    ///
    SocketT* _socket;
    ///
    StateMachine _state;
    ///
    size_t _writeCursor;
}

Documentation

A low-level writer for the HTTP/1.0 and HTTP/1.1 protocols.

Performance

No explicit effort has been made to optimise this writer for performance, but it should be reasonably fast.

Memory wise the writer does not directly allocate heap memory as it uses the user-provided buffer, however the I/O calls can of course do whatever they want.

If the writer would have to perform more than 1 flush due to the data being larger than the buffer, then the writer will perform two flushes at most - one for the currently buffered data, and one for the entire remaining data (without needing to buffer the remaining data directly).

Buffer

The writer operates directly on a buffer provided by the user.

The size of the buffer dictates how many bytes can be stored before a flush is forced. Certain actions, such as calling finishMessage, will also force a flush.

Generally the idea of the buffer is to reduce the amount of I/O calls, more than anything else.

Flow

The writer is a low-level, state-machine API, and thus requires quite a lot of involvement from the user as well as a magical incantation of calls to create fully valid HTTP messages.

Similar to the Http1Readerany HttpErrorresult will contain a valid HTTP response, however it's not really useful due to the fact these errors will almost always occur mid-message, making it impossible to relay the information to the client.

Generally, if a protocol error is encountered simply close the connection.

RequestFlow

  1. Call putRequestLineto write the request line.

  2. Call putHeaderto write any headers.

  3. If you plan to write a body, you must either write a content-lengthheader, or write a transfer-encoding: chunkedheader.

  4. Call finishHeadersto finish the headers.

  5. Call putBodyto write any body data, if any.

  6. Call finishBodyto finish the body.

  7. Call finishMessageto finish the message.

ResponseFlow

The response flow is very similar to the request flow except we need to account for being able to write trailer headers.

  1. Call putResponseLineto write the response line.

  2. Call putHeaderto write any headers.

  3. If you plan to write a body, you must either write a content-lengthheader, or write a transfer-encoding: chunkedheader.

  4. Call finishHeadersto finish the headers.

  5. Call putBodyto write any body data, if any.

  6. Call finishBodyto finish the body.

  7. If the transfer-encoding: chunkedheader was written:

  8. Call putTrailerto write any trailer headers, if any.

  9. Call finishTrailerto finish the trailer headers. You must do this regardless of if you wrote/can use trailers.

  10. Call finishMessageto finish the message.

Notes

The writer currently does not support scattered writes.

The writer will never close the socket as it does not have ownership of it.

Security

The writer internally makes use of a type-system-based state machine to make it more difficult to perform a bad state transition.

No other specific security issues are addressed beyond ensuring that the data written is valid according to RFC 9110 & 9112

Issues

The writer is currently in an early state, and is not yet ready for production.

The current API is not stable, and may change in the future.

The writer does not natively perform compression.

The writer is not very extensively tested yet.

Specific differences between HTTP/1.0 and HTTP/1.1 are not fully implemented, as HTTP/1.1 has been the main focus.

Aliases

Name Description
Machine
StateMachine
finishHeaders

Finishes the headers.

finishTrailers

Ditto.

putHeader

Writes a single header.

putTrailer

Ditto.

Enums

Name Description
BodyEncoding
State

Functions

Name Description
bufferHeaderName
bufferedWrite
finishBody

Finishes the body.

finishHeadersImpl
finishMessage

Acknowledges that the entire HTTP message has been written, and returns a summary

flush
processHeader
putBody

Writes body data.

putBodyChunked
putBodyContentLength
putHeaderImpl
putRequestLine

Writes an entire request line. This will configure this writer to be a request writer for the remainder of the message, until finishMessageis called.

putResponseLine

Writes an entire response line. This will configure this writer to be a response writer for the remainder of the message, until finishMessageis called.

putResultResponse

Writes the HTTP message stored within the provided resultto the socket.

Structs

Name Description
MessageState

Variables

Name Description
_buffer
_config
_message
_socket
_state
_writeCursor