GopherProxy

	tdesign.txt - clic - Clic is an command line interactive client for gopher writ…
	git clone git://bitreich.org/clic/ git://hg6vgqziawt5s4dj.onion/clic/
	Log
	Files
	Refs
	Tags
	LICENSE
	---
	tdesign.txt (3830B)
	---
	1
	2 -- text --
	3
	4 $Id$
	5
	6
	7 usocket: Universal sockets library
	8 ==================================
	9
	10 Contents
	11 ========
	12
	13 * Motivation
	14 * Design goal
	15 * Functional requirements
	16 * Class structure
	17
	18
	19
	20 Motivation
	21 ==========
	22
	23 There are 2 other portability sockets packages [that I know of]
	24 out there:
	25
	26 1) trivial-sockets
	27 2) acl-compat (which is a lot broader, but contains sockets too)
	28
	29 The first misses some functionality which is fundamental when
	30 the requirements stop being 'trivial', such as finding out the
	31 addresses of either side connected to the tcp/ip stream.
	32
	33 The second, being a complete compatibility library for Allegro,
	34 contains much more than only sockets. Next to that, as the docs
	35 say, is it mainly directed at providing the functionality required
	36 to port portable-allegroserve - meaning it may be (very) incomplete
	37 on some platforms.
	38
	39 So, that's why I decided to inherit Erik Enge's project to build
	40 a library with the intention to provide portability code in only
	41 1 area of programming, targeted at 'not so trivial' programming.
	42
	43 Also, I need this library to extend cl-irc with full DCC functionality.
	44
	45
	46
	47 Design goal
	48 ===========
	49
	50 To provide a portable TCP/IP socket interface for as many
	51 implementations as possible, while keeping the portability layer
	52 as thin as possible.
	53
	54
	55
	56 Functional requirements
	57 =======================
	58
	59 The interface provided should allow:
	60 - 'client'/active sockets
	61 - 'server'/listening sockets
	62 - provide the usual stream methods to operate on the connection stream
	63 (not necessarily the socket itself; maybe a socket slot too)
	64
	65 For now, as long as there are no possibilities to have UDP sockets
	66 to write a DNS client library: (which in the end may work better,
	67 because in this respect all implementations are different...)
	68 - retrieve IP addresses/ports for both sides of the connection
	69
	70 Several relevant support functionalities will have to be provided too:
	71 - long <-> quad-vector operators
	72 - quad-vector <-> string operators
	73 - hostname <-> quad-vector operators (hostname resolution)
	74
	75
	76 Minimally, I'd like to support:
	77 - SBCL
	78 - CMUCL
	79 - ABCL (ArmedBear)
	80 - clisp
	81 - Allegro
	82 - LispWorks
	83 - OpenMCL
	84
	85
	86 Comments on the design above
	87 ============================
	88
	89 I don't think it's a good idea to implement name lookup in the
	90 very first of steps: we'll see if this is required to get the
	91 package accepted; not all implementations support it.
	92
	93 Name resolution errors ...
	94 Since there is no name resolution library (yet), nor standardized
	95 hooks into the standard C library to do it the same way on
	96 all platforms, name resolution errors can manifest themselves
	97 in a lot of different ways. How to marshall these to the
	98 library users?
	99
	100 Several solutions come to mind:
	101
	102 1) Map them to 'unknown-error
	103 2) Give them their own errors and map to those
	104 ... which implies that they are actually supported atm.
	105 3) ...
	106
	107 Given that the library doesn't now, but may in the future,
	108 include name resolution officially, I tend to think (1) is the
	109 right answer: it leaves it all undecided.
	110
	111 These errors can be raised by the nameresolution service
	112 (netdb.h) as values for 'int h_errno':
	113
	114 - HOST_NOT_FOUND (1)
	115 - TRY_AGAIN (2) /* Server fail or non-authoritive Host not found */
	116 - NO_RECOVERY (3) /* Failed permanently */
	117 - NO_DATA (4) /* Valid address, no data for requested record */
	118
	119 int *__h_errno_location(void) points to thread local h_errno on
	120 threaded glibc2 systems.
	121
	122
	123 Class structure
	124 ===============
	125
	126 usocket
	127 \|
	128 +- datagram-usocket
	129 +- stream-usocket
	130 \- stream-server-usocket
	131
	132 The usocket class will have methods to query local properties, such
	133 as:
	134
	135 - get-local-name: to query to which interface the socket is bound
	136 - <other socket and protocol options such as SO_REUSEADDRESS>