shakhmetov / libcno

There can never be enough http (2) libraries.

What.

Socketless HTTP 2.

Why.

Mostly because libuv, and therefore libh2o, tends to segfault a lot when used from Python. Also, because why not?

C API

make obj/libcno.a

Just read core.h. And common.h, for buffers and error handling. And hpack.h for headers. Basically, you create a cno_connection_t, then follow a simple chain of cno_init -> connect some callbacks -> cno_begin -> cno_consume -> (repeat while I/O is still possible) -> cno_eof -> cno_fini, skipping to the last step if anything returns an error and using cno_write_head + cno_write_data or cno_write_push or cno_write_reset to send some stuff of your own.

Python API

pip3 install cffi
pip3 install git+https://github.com/pyos/libcno

C constant	Python constant
CNO_CLIENT	cno.raw.CNO_CLIENT
etc.	...

cno.raw.Connection is an almost complete 1:1 mapping to C API functions.

C function	cno.raw.Connection method
cno_init(c, CNO_SERVER)	c = cno.raw.Connection(server=True)
cno_fini(c)	del c
cno_begin(c, CNO_HTTP2)	c.connection_made(is_http2=True)
cno_eof(c)	c.connection_lost()
cno_consume(c, data, length)	c.data_received(data)
cno_next_stream(c)	c.next_stream
cno_write_head(c, stream, msg, final)	c.write_head(stream, code, method, path, headers, final)
cno_write_push(c, stream, msg)	c.write_push(stream, method, path, headers)
cno_write_data(c, stream, data, length, final)	c.write_data(stream, data, final)
cno_write_reset(c, stream, code)	c.write_reset(stream, code)

Event receivers must be defined as methods of Connection subclasses.

C event	cno.raw.Connection method
on_writev(iov, iovcnt)	def on_writev(self, chunks)
on_stream_start(stream)	def on_stream_start(self, stream)
on_stream_end(stream, code, side)	def on_stream_end(self, stream, code, side)
on_flow_increase(stream)	def on_flow_increase(self, stream)
on_message_head(stream, msg)	def on_message_head(self, stream, code, method, path, headers)
on_message_tail(stream, msg)	def on_message_tail(self, stream, trailers)
on_message_data(stream, data, length)	def on_message_data(self, stream, data)
on_message_push(stream, msg, parent)	def on_message_push(self, stream, parent, method, path, headers)

On Python 3.5+, higher-level asyncio bindings are also available. Server:

async def handle(request: cno.Request):
    request.method   # :: str
    request.path     # :: str
    request.headers  # :: [(str, str)]
    request.conn     # :: cno.Server -- `protocol` (below)
    request.payload  # :: asyncio.StreamReader

    # Pushed resources inherit :authority and :scheme from the request unless overriden.
    request.push('GET', '/index.css', [('x-extra-header', 'value')])

    if all_data_is_available:
        await request.respond(200, [('content-length', '4')], b'!!!\n')
    else:
        # `Channel` is a subclass of `asyncio.Queue`.
        channel = cno.Channel(max_buffered_chunks, loop=request.conn.loop)
        await channel.put(b'!!!')  # this should preferably be done in a separate
        await channel.put(b'\n')   # coroutine, naturally.
        channel.close()
        # Or you can use any async iterable instead.
        await request.respond(200, [], channel)

make_protocol = lambda: cno.Server(event_loop, handle)
# When using TLS, don't forget to tell clients you support HTTP 2:
# ssl_context.set_alpn_protocols(['h2', 'http/1.1'])
# ssl_context.set_npn_protocols(['h2', 'http/1.1'])
# server = await event_loop.create_server(make_protocol, '', 8000, ssl=ssl_context)

Client:

client = await cno.connect(event_loop, 'https://example.com/')
client.loop       # :: asyncio.BaseEventLoop -- `event_loop`
client.transport  # :: asyncio.Transport
client.is_http2   # :: bool
client.scheme     # :: str  -- https
client.authority  # :: str  -- example.com

response = await client.request('GET', '/', [('user-agent', 'libcno/0.1')])  # cno.Response
response.code     # :: int
response.headers  # :: [(str, str)]
response.payload  # :: asyncio.StreamReader
async for push in response.pushed:
    push.method   # :: str
    push.path     # :: str
    push.headers  # :: [(str, str)]
    await push.response  # :: cno.Response
    # or push.cancel()

response = await client.request('POST', '/whatever', [], b'payload')
# `request`, like `respond`, also accepts `cno.Channel`s as payload.

client.close()

# `cno.connect` automatically sets up a default SSL context and creates
# a TCP connection. To simply create an `asyncio.Protocol`:
client = cno.Client(event_loop, authority='example.com', scheme='https')

# A shorthand for `cno.connect` followed by `client.request`:
response = await cno.request(event_loop, 'GET', 'https://example.com/path', ...)
response.conn.close()