package utcp

  1. Overview
  2. Docs
An implementation of TCP (Transmission Control Protocol) in OCaml

Install 

dune-project
 Dependency

git.robur.coop Readme Changelog ISC License Edit opam file Versions (9)

Authors

  1. R
    Robur <team@robur.coop>

Maintainers

  1. R
    Robur <team@robur.coop>

Sources

utcp-0.0.8.tbz
md5=221e1c5779a24a265c9043f65ec79611
sha512=cc1b07dbfbc43985c25e8068f7664613e4e15e2a7832771d99dca3558f37f8dc839f79b4166f2697b7ac487693a9451a0b7b35ae3747a9565b43e4d31f0f2ae3

doc/utcp/Utcp/index.html

Module UtcpSource

µTCP - an implementation of the Transmission Control Protocol

TCP is a widely used protocol on the Internet. µTCP has its origins in the Netsem (network semantics) research project, which is an executable specification of TCP/IP and the Unix sockets API in HOL4.

µTCP was manually translated from the HOL4 specification into OCaml, and decisions were taken where needed. There is no support for out of band data (urgent pointers). TCP timestamps are also not supported (due to its dubious use).

TCP is mainly specified in RFC 9293.

Abstract state type

Sourcetype 'a state

The abstract type of an immutable state of the TCP stack.

Sourceval empty : (unit -> 'a) -> string -> 'a state

empty make_notify id constructs an empty TCP state with a function how to create a notifications, and an identifier for the TCP stack.

Sourceval start_listen : 'a state -> int -> 'a state

start_listen t port adds port to the set of listened to ports.

Sourceval stop_listen : 'a state -> int -> 'a state

stop_listen t port removes port from the set of listened to ports.

Sourcetype flow

The abstract type of a flow - a connection between this TCP stack and a remote endpoint.

Sourceval pp_flow : flow Fmt.t

pp_flow flow pretty-prints the flow.

Sourceval num_connections : 'a state -> int

num_connections t is the number of connections in any state

Sourceval peers : flow -> (Ipaddr.t * int) * (Ipaddr.t * int)

peers flow is the two endpoints of the flow, each identifiable by their IP and port.

Sourcemodule Sequence : sig ... end

The module of TCP sequence numbers (unsigned 32 bit values, arithmetic operations may wrap), comparison adheres to serial number arithmetics from RFC 1982.

Sourcemodule Segment : sig ... end

The module of TCP segments, as seen on the wire.

The type for outputting packets: a triple of source IP address, destination IP address, and segment.

Sourceval timer : 'a state -> Mtime.t -> 'a state * (flow * [ `Retransmission_exceeded | `Timer_2msl | `Timer_connection_established | `Timer_fin_wait_2 ] * 'a * 'a) list * output list

timer state now runs the TCP timer at now for state. It results in a new state, a list of errors (a quadruple of flow, concrete error, and receive and send notification), and a list of segments to send out.

Sourceval handle_buf : 'a state -> Mtime.t -> src:Ipaddr.t -> dst:Ipaddr.t -> Cstruct.t -> 'a state * [ `Established of flow * [ `Active of 'a | `Passive ] | `Drop of flow * 'a list | `Received of flow * [ `Data | `Eof ] * 'a | `Send of flow * 'a ] list * output list

handle_buf state now ~src ~dst buf handles the buffer buf for the TCP stack. This results in a fresh state, optionally a change in the flow (Established, Drop, Received, Send), and a list of segments to send.

Sourceval connect : src:Ipaddr.t -> ?src_port:int -> dst:Ipaddr.t -> dst_port:int -> 'a state -> Mtime.t -> ('a state * flow * 'a * output, [ `Msg of string ]) result

connect ~src ?src_port ~dst ~dst_port state now starts a TCP connection from src, src_port to dst, dst_port. The src_port will be picked at random if not provided. The output is a fresh TCP state, the flow, a notification, and a segment to send out.

Sourcetype tcp_state

The type for the TCP state machine

Sourceval tcp_state_to_string : tcp_state -> string

tcp_state_to_string state results in a printable string of state.

Sourcetype error = [
  1. | `Not_found
  2. | `Bad_state of string * tcp_state
  3. | `Msg of string
]

The error type for user API functions.

Sourceval pp_error : error Fmt.t

pp_error ppf error pretty-prints the error on the pretty printer ppf.

Sourceval close : 'a state -> Mtime.t -> flow -> ('a state * 'a list * output list, error) result

close state now flow closes flow. It results either in a fresh TCP state, a list of changes in the flow (conditions to be notified), and a list of segments to send out, or an error (if the flow cannot be found, or some other error).

Sourceval shutdown : 'a state -> Mtime.t -> flow -> [ `read | `write | `read_write ] -> ('a state * 'a list * output list, error) result

shutdown state now flow direction shuts the flow down in the given direction. It results in a fresh TCP state, a list of changes in the flow (conditions to be notified), and a list of segments to send out, or an error.

Sourceval recv : 'a state -> Mtime.t -> flow -> ('a state * string list * 'a * output list, [ error | `Eof ]) result

recv state now flow receives data for flow. The read notification is also provided - if there's no awaiting data, this notification can be waited on.

Sourceval send : 'a state -> Mtime.t -> flow -> ?off:int -> ?len:int -> string -> ('a state * int * 'a * output list, error) result

send state now flow ~off ~len data sends data on flow, starting at off (defaults to 0) of length len (defaults to data until the end). This outputs a fresh TCP state, the number of bytes enqueued, the write notification, and a list of segments to send.

Sourceval force_enqueue : 'a state -> Mtime.t -> flow -> ?off:int -> ?len:int -> string -> ('a state, error) result

force_enqueue state now flow ~off ~len data pushes data on flow, starting at off (defaults to 0) of length len (defaults to data until the end) onto the send queue. This may exceed the send queue size, use with caution.