Networking Libraries

In that ModernBill is designed to automate and control other pieces of a complete system, it relies on its ability to network, or interface with remote systems. To satisfy this need, ModernBill has many networking libraries:

The Curl class

Provides an object-oriented interface to the system cURL library (libcurl) via:

1. PHP's curl extension.
2. The curl command-line utility.

Nearly all modules use this for HTTP calls.

Files of interest:

/lib-mbapi/include/curl/curl.php

Provides the Curl class itself.

/app-lib/include/config/config.php

Configuration options in the section labelled cURL SETTINGS.

The IPC classes

Provides an object-oriented interface to the System-V Inter-Process Communication functions provided by the sysvsem, sysvshm, and sysvmsg PHP extensions.

Files of interest:

/lib-tk/include/io/ipc.php

Provides the following classes:

System V Message Queues

• struct msg_perm as QueuePermissions
• struct msqid_ds as QueueState
• struct msgp as Message
• int msqid as MessageQueue

System V Semaphores

• int semid as Semaphore

System V Shared Memory

• int shmid as SharedMemory
• int shmid and int semid as ProtectedSharedMemory

Provides the following functions:

get_ipc_key()

Provides a unique identifier for initializing an IPC resource.

The NamedPipe class

Provides an object-oriented interface to non-blocking I/O operations over any kind of pipe, including named pipes (Unix FIFO files). Its main design feature is that it safely waits for broken pipes to be reestablished. This is useful for command-line integrations with fast, persistent, named connections.

Files of interest:

/lib-tk/include/io/fifo.php

Provides the NamedPipe class.

/app-modernbill-api/mbapi.php

Implements an interface to the MBAPI on top of the NamedPipe class.

/app-modernbill-api/mbapilib.*

Libraries which glue various languages to the MBAPI.

The Real-Time I/O classes

Provides an elaborate system for multiplexing I/O tasks, or any kind of task, based on a real-time scheduler and an integrated I/O polling framework. Built on top of this are HTTP and Whois clients.

Files of interest...

Portability functions:

/lib-tk/include/io/time.php

Provides portable microtime_float() function.

/lib-tk/include/io/identity.php

Provides portable identity() function and ObjectSet class, providing a way to hash by object instance.

Data structures:

/lib-tk/include/io/buffer.php

Provides Buffer class, providing an easy interface to common string operations.

/lib-tk/include/io/queue.php

Provides Queue and QueueItem classes, for providing an object queue.

/lib-tk/include/io/tree.php

Provides Tree and Earth classes, and a plant() factory function, implementing a binary search tree.

/lib-tk/include/io/flags.php

Provides Flags and BitMask classes, and the registerFlags(), registerFlagSet, and registerFlagOptions() functions, for providing easy ways of viewing and manipulating bitmasks, for making debugging easier.

/lib-tk/include/io/timeline.php

Provides TimePoint and TimeEvent classes, a queue for events at a particular point in time.

Provides TimeRange and TimeLine classes, where the time-line is a time-range containing a tree of time-points containing event-queues.

/lib-tk/include/io/task_schedule.php

Provides Schedule and ScheduleEvent classes, a TimeLine for handling TimeEvents associated with a Task and a task-event: "start", "out", or "stop".

Provides Task class, a base for implementing time-triggered methods which operate on a target. Each target is represented by a queue of tasks waiting to do work on the target, provided by TaskQueue and TaskQueueItem, which contains a reference back to the Task. As task-events are triggered, they move from the schedule to the task; specifically, from the task-event-queue at the time-point in the schedule to the task-queue on the target.

Provides MetaTask and EventCallback classes, a base for linking stages of tasks together. MetaTask uses EventCallbacks to tie the completion of one sub-task to the start of another.

Provides TaskPollRegistration, an interface for polling the schedule for task events, for triggering actions external to the operation of a task, based on an event internal to the operation of a task.

Resource structures:

/lib-tk/include/io/stream.php

Provides Pipe class, a base for InPipe and OutPipe, paired inside a Stream base for ProcStream and SocketStream.

Pipe

Methods common to any kind of half-duplex, unidirectional pipe.

InPipe

Provides input methods.

OutPipe

Provides output methods.

Stream

Provides interface for full-duplex, bidirectional communication based on two unidirectional pipes. The pair of pipes may refer to the same underlying full-duplex resource.

ProcStream

Provides interface for the stdin and stdout of a shell command.

SocketStream

Provides interface to a BSD socket.

/lib-tk/include/io/poll.php

Poller

Provides a poll(2)-style interface to the stream_select() PHP function, which actually uses the select(2) system call. This interface was chosen for future support for epoll(2) and kqueue(2).

PollRegistration

Represents a stream associated with a network availability event. These are registered or unregistered with the class Poller.

BitRefs

Used by Poller to count references to registered events. Events can be registered in a nested fashion: events can be registered any number of times, and are only unregistered when unregistered as many times as registered.

Operational structures:

/lib-tk/include/io/realtime.php

RealTimeStream

Represents a scheduler associated with a stream, and satisfies network availability events with I/O operations. A stream can only be managed by one scheduler at a time.

RealTimePipeBuffer

An extension of TaskQueue associated with a RealTimeStream and a Buffer.

RealTimeInPipeBuffer

An extension of RealTimePipeBuffer which provides a method for reading from the stream into a buffer.

RealTimeOutPipeBuffer

An extension of RealTimePipeBuffer which provides a method for writing to the stream from a buffer.

RealTimeIO

An extension of Schedule which waits on network availability via Poller, firing events on RealTimeStream task targets.

RealTimeTask

An extension of Task which initializes the I/O task-queue on the target, and registers network availability events on the RealTimeIO's internal Poller.

RealTimeInputTask, RT_INPUT

An extension of RealTimeTask which provides a base for reading input from a stream.

RealTimeOutputTask, RT_OUTPUT

An extension of RealTimeTask which provides a base for writing output to a stream.

RealTimeDelimitedInputTask

An extension of RealTimeInputTask which provides a base for reading input from a stream until a delimiter is reached.

RealTimeReadlineTask, RT_READLINE

An extension of RealTimeDelimitedInputTask which sets the delimiter to "\n", a newline.

RealTimeMBAPIResponseTask

An extension of RealTimeDelimitedInputTask which sets the delimiter to "<?mb end ?>", the MBAPI command delimiter in the MBAPI stream protocol.

RealTimeHTTPResponseHeaderTask

An extension of RealTimeDelimitedInputTask which sets the delimiter to "\r\n\r\n" (CRNL CRNL).

RealTimeMatchInputTask, RT_MATCH

An extension of RealTimeInputTask which looks for a pattern until EOF.

/lib-tk/include/io/http.php

Provides an HTTP 1.1 compliant client. It is implemented as a meta-task which controls the flow of underlying input and output tasks. Classes representing components of HTTP requests and responses are also provided.

Public request and response structures:

HTTPRequestLine

Represents an HTTP request line comprised of the following:

1. String method
2. HTTPURI uri
3. String protocol
4. String version

HTTPResponseLine

Represents an HTTP response line comprised of the following:

1. String protocol
2. String version
3. String code

HTTPDocument

Represents binary data and its MIME type:

1. String mime_type
2. String content

URLArg

Represents a single URL argument:

1. String name
2. String value

URLArgs

Represents a list of URL arguments:

1. Indexed array args

HTTPURI

Represents an HTTP URI comprised of the following:

1. String path
2. String query
3. URLArgs args
4. String fragment

HTTPURL

Represents an HTTP URL comprised of the following:

1. String scheme
2. String host
3. Integer port
4. String user
5. String pass
6. HTTPURI uri

HTTPClientTask

Provides a meta-task which implements an HTTP client.

Operational structures:

HTTPHeaders

Provides representation and serialization for HTTP headers.

/lib-tk/include/io/whois.php

Provides a whois client with support for:

Protocols

1. whois
2. whois2
3. HTTP/HTTPS whois

Statuses

1. Available
2. Unavailable
3. Error:
   1. Service Rejected
   2. String message from underlying networking error

Public request structures:

WhoisCondition

A pattern match condition for evaluating a whois response status:

1. String pattern
2. Boolean not

WhoisService

Describes a whois service:

1. BitMask("whois protocol") protocol
2. String host
3. Integer port
4. WhoisCondition available_condition
5. WhoisCondition reject_condition

AsyncWhois

Using RealTimeIO and WhoisTarget, provides asynchronous whois lookups:

1. Indexed Array domainSLDs
2. Mixed Array domainTLDs of values indexed by:

   Integer

   String tld using default whois service

   String tld

   WhoisService whois_service

3. String callback of the form:
   1. String sld
   2. String tld
   3. Mixed available

      TRUE

      Available

      FALSE

      Unavailable

      NULL

      Indeterminate

      String

      Error message

4. Float timeout

Operational structures:

WhoisTarget

Provides a target for whois meta-tasks which yields the underlying target for sub-tasks, and request information.

1. String sld
2. String tld
3. WhoisService whois_service
4. String callback

WhoisTask

An extension of MetaTask which implements whois and whois2 clients.

HTTPWhoisTask

An extension of HTTPClientTask which implements whois over HTTP and HTTPS.