The s-http-client Reference Manual

This is the s-http-client Reference Manual, version 1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 17:49:34 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 s-http-client

A Basic HTTP Client

Maintainer

Sven Van Caekenberghe <>

Author

Sven Van Caekenberghe <>

License

Lesser Lisp General Public License (LLGPL)

Long Description

A Basic HTTP Client

Version

1

Dependencies
  • s-utils (system).
  • s-sysdeps (system).
  • s-base64 (system).
  • puri (system).
  • chipz (system).
Source

s-http-client.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 s-http-client/src

Source

s-http-client.asd.

Parent Component

s-http-client (system).

Child Components

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


4.1 Lisp


4.1.1 s-http-client/s-http-client.asd

Source

s-http-client.asd.

Parent Component

s-http-client (system).

ASDF Systems

s-http-client.


4.1.2 s-http-client/src/package.lisp

Source

s-http-client.asd.

Parent Component

src (module).

Packages

s-http-client.


4.1.3 s-http-client/src/http-client.lisp

Dependency

package.lisp (file).

Source

s-http-client.asd.

Parent Component

src (module).

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 s-http-client

A Basic HTTP Client

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


6.1 Public Interface


6.1.1 Special variables

Special Variable: *default-http-client-state*

The default, globally shared HTTP client state

Package

s-http-client.

Source

http-client.lisp.

Special Variable: *http-client-accept*

The value to use for the ’Accept’ request header

Package

s-http-client.

Source

http-client.lisp.

Special Variable: *http-client-accept-encoding*

The value to use for the ’Accept-Encoding’ request header

Package

s-http-client.

Source

http-client.lisp.

Special Variable: *http-client-agent*

The value to use for the ’User-Agent’ request header

Package

s-http-client.

Source

http-client.lisp.


6.1.2 Ordinary functions

Function: close-all-connections (&optional http-client-state &key abort)

Close all open connections in http-client-state, optionaly aborting them

Package

s-http-client.

Source

http-client.lisp.

Function: do-http-request (uri &key method content content-type content-length body basic-authorization headers proxy state connect-timeout read-timeout write-timeout)

Execute an HTTP request, returns (VALUES body code headers uri kept-alive-state)

Package

s-http-client.

Source

http-client.lisp.

Function: make-http-client-state ()

Make a new HTTP client state object to hold open (keepalive) connections

Package

s-http-client.

Source

http-client.lisp.

Function: uri-decode-for-query (string)

URI decode string from a query parameter value

Package

s-http-client.

Source

http-client.lisp.

Function: uri-encode-for-query (string &key signal-errors)

URI encode string for use as a query parameter value

Package

s-http-client.

Source

http-client.lisp.


6.1.3 Standalone methods

Method: print-object ((state http-server-state) stream)
Source

http-client.lisp.


6.1.4 Classes

Class: http-client-state

Object holding all HTTP client state

Package

s-http-client.

Source

http-client.lisp.

Direct methods
Direct slots
Slot: data
Slot: lock
Initform

(s-sysdeps:make-process-lock "http-client-state")

Readers

get-lock.

Writers

This slot is read-only.


6.2 Internals


6.2.1 Special variables

Special Variable: *connection-keep-alive-timeout*

Keep-Alive connections not used for this amount of time will be force closed, eventually

Package

s-http-client.

Source

http-client.lisp.

Special Variable: *endpoint*
Package

s-http-client.

Source

http-client.lisp.

Special Variable: +common-response-headers+
Package

s-http-client.

Source

http-client.lisp.

Special Variable: +uri-encode-char-map+
Package

s-http-client.

Source

http-client.lisp.


6.2.2 Ordinary functions

Function: close-connection (connection &key abort)

Close a socket connection stream, optionally aborting

Package

s-http-client.

Source

http-client.lisp.

Function: concatenate-chunks (chunks total-size)
Package

s-http-client.

Source

http-client.lisp.

Function: do-http-request-internal (scheme host port state method uri content content-type content-length body basic-authorization headers connect-timeout read-timeout write-timeout)
Package

s-http-client.

Source

http-client.lisp.

Function: do-one-request-response (connection uri method buffer &key content content-type content-length body basic-authorization headers)

Do one HTTP request and response on stream

Package

s-http-client.

Source

http-client.lisp.

Function: encode-basic-authorization (username-password-pair)
Package

s-http-client.

Source

http-client.lisp.

Function: format-http-request-line (stream format-string &rest args)
Package

s-http-client.

Source

http-client.lisp.

Function: get-open-connection (scheme host port state &key force-new connect-timeout read-timeout write-timeout)

Get an open connection to scheme://host:port reusing one from state unless force-new is t. Release after use

Package

s-http-client.

Source

http-client.lisp.

Function: gunzip (string)
Package

s-http-client.

Source

http-client.lisp.

Function: header-field-name->keyword (string &optional start end)
Package

s-http-client.

Source

http-client.lisp.

Function: header-field-value->string (string &optional start end)
Package

s-http-client.

Source

http-client.lisp.

Function: open-socket-stream (scheme host port &key connect-timeout read-timeout write-timeout)
Package

s-http-client.

Source

http-client.lisp.

Function: read-crlf-line (buffer stream &optional eof-error-p eof-value)

Read a CRLF termintated line from a character input stream into buffer. Return length excluding CRLF.

Package

s-http-client.

Source

http-client.lisp.

Function: read-response (stream buffer &optional body body-expected)

Read an HTTP response, headers and content, from stream

Package

s-http-client.

Source

http-client.lisp.

Function: release-connection (scheme host port state connection)

Release a connection obtained through get-open-connection (either stored in state for reuse or not)

Package

s-http-client.

Source

http-client.lisp.

Function: response-read-body (stream length body buffer)
Package

s-http-client.

Source

http-client.lisp.

Function: response-read-chunked-body (stream body buffer)
Package

s-http-client.

Source

http-client.lisp.

Function: response-read-code (stream buffer)
Package

s-http-client.

Source

http-client.lisp.

Function: response-read-headers (stream buffer)
Package

s-http-client.

Source

http-client.lisp.

Function: response-read-undefined-body (stream body buffer)
Package

s-http-client.

Source

http-client.lisp.

Function: write-http-request-line (string stream)
Package

s-http-client.

Source

http-client.lisp.

Function: write-request (stream buffer uri method &key content content-type content-length basic-authorization headers)

Write an HTTP request, full header and body, to stream

Package

s-http-client.

Source

http-client.lisp.


6.2.3 Generic functions

Generic Function: cleanup-old-connections (http-client-state)
Package

s-http-client.

Methods
Method: cleanup-old-connections ((http-client-state http-client-state))

Force close all kept-alive connections that are too old

Source

http-client.lisp.

Generic Function: close-all-connections-internal (http-client-state &key abort)
Package

s-http-client.

Methods
Method: close-all-connections-internal ((http-client-state http-client-state) &key abort)
Source

http-client.lisp.

Generic Reader: get-buffer (object)
Package

s-http-client.

Methods
Reader Method: get-buffer ((http-server-state http-server-state))

automatically generated reader method

Source

http-client.lisp.

Target Slot

buffer.

Generic Writer: (setf get-buffer) (object)
Package

s-http-client.

Methods
Writer Method: (setf get-buffer) ((http-server-state http-server-state))

automatically generated writer method

Source

http-client.lisp.

Target Slot

buffer.

Generic Reader: get-endpoint (condition)
Generic Writer: (setf get-endpoint) (condition)
Package

s-http-client.

Methods
Reader Method: get-endpoint ((condition http-client-error))
Writer Method: (setf get-endpoint) ((condition http-client-error))
Source

http-client.lisp.

Target Slot

endpoint.

Generic Function: get-http-server-state (http-client-state scheme-host-port)
Package

s-http-client.

Methods
Method: get-http-server-state ((http-client-state http-client-state) scheme-host-port)
Source

http-client.lisp.

Generic Reader: get-in-use-p (object)
Package

s-http-client.

Methods
Reader Method: get-in-use-p ((http-server-state http-server-state))

automatically generated reader method

Source

http-client.lisp.

Target Slot

in-use-p.

Generic Writer: (setf get-in-use-p) (object)
Package

s-http-client.

Methods
Writer Method: (setf get-in-use-p) ((http-server-state http-server-state))

automatically generated writer method

Source

http-client.lisp.

Target Slot

in-use-p.

Generic Function: get-kept-alive-age (http-server-state)
Package

s-http-client.

Methods
Method: get-kept-alive-age ((http-server-state http-server-state))
Source

http-client.lisp.

Generic Reader: get-lock (object)
Package

s-http-client.

Methods
Reader Method: get-lock ((http-client-state http-client-state))

automatically generated reader method

Source

http-client.lisp.

Target Slot

lock.

Generic Reader: get-scheme-host-port (object)
Package

s-http-client.

Methods
Reader Method: get-scheme-host-port ((http-server-state http-server-state))

automatically generated reader method

Source

http-client.lisp.

Target Slot

scheme-host-port.

Generic Writer: (setf get-scheme-host-port) (object)
Package

s-http-client.

Methods
Writer Method: (setf get-scheme-host-port) ((http-server-state http-server-state))

automatically generated writer method

Source

http-client.lisp.

Target Slot

scheme-host-port.

Generic Reader: get-socket (object)
Package

s-http-client.

Methods
Reader Method: get-socket ((http-server-state http-server-state))

automatically generated reader method

Source

http-client.lisp.

Target Slot

socket.

Generic Writer: (setf get-socket) (object)
Package

s-http-client.

Methods
Writer Method: (setf get-socket) ((http-server-state http-server-state))

automatically generated writer method

Source

http-client.lisp.

Target Slot

socket.

Generic Reader: get-timeout (condition)
Generic Writer: (setf get-timeout) (condition)
Package

s-http-client.

Methods
Reader Method: get-timeout ((condition http-client-error))
Writer Method: (setf get-timeout) ((condition http-client-error))
Source

http-client.lisp.

Target Slot

timeout.

Generic Reader: get-timestamp (object)
Package

s-http-client.

Methods
Reader Method: get-timestamp ((http-server-state http-server-state))

automatically generated reader method

Source

http-client.lisp.

Target Slot

timestamp.

Generic Writer: (setf get-timestamp) (object)
Package

s-http-client.

Methods
Writer Method: (setf get-timestamp) ((http-server-state http-server-state))

automatically generated writer method

Source

http-client.lisp.

Target Slot

timestamp.


6.2.4 Conditions

Condition: http-client-connection-error
Package

s-http-client.

Source

http-client.lisp.

Direct superclasses

http-client-error.

Condition: http-client-error
Package

s-http-client.

Source

http-client.lisp.

Direct superclasses

error.

Direct subclasses
Direct methods
Direct slots
Slot: endpoint
Initform

(quote nil)

Initargs

:endpoint

Readers

get-endpoint.

Writers

(setf get-endpoint).

Slot: timeout
Initform

(quote nil)

Initargs

:timeout

Readers

get-timeout.

Writers

(setf get-timeout).

Condition: http-client-read-error
Package

s-http-client.

Source

http-client.lisp.

Direct superclasses

http-client-error.

Condition: http-client-write-error
Package

s-http-client.

Source

http-client.lisp.

Direct superclasses

http-client-error.


6.2.5 Classes

Class: http-server-state

Object holding a reusable open connection to a scheme://host:port

Package

s-http-client.

Source

http-client.lisp.

Direct methods
Direct slots
Slot: scheme-host-port
Initargs

:scheme-host-port

Readers

get-scheme-host-port.

Writers

(setf get-scheme-host-port).

Slot: socket
Initargs

:socket

Readers

get-socket.

Writers

(setf get-socket).

Slot: in-use-p
Readers

get-in-use-p.

Writers

(setf get-in-use-p).

Slot: buffer
Initform

(make-string 4096)

Readers

get-buffer.

Writers

(setf get-buffer).

Slot: timestamp
Initform

(get-universal-time)

Readers

get-timestamp.

Writers

(setf get-timestamp).


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
C   D   E   F   G   H   M   O   P   R   U   W  
Index Entry  Section

(
(setf get-buffer): Private generic functions
(setf get-buffer): Private generic functions
(setf get-endpoint): Private generic functions
(setf get-endpoint): Private generic functions
(setf get-in-use-p): Private generic functions
(setf get-in-use-p): Private generic functions
(setf get-scheme-host-port): Private generic functions
(setf get-scheme-host-port): Private generic functions
(setf get-socket): Private generic functions
(setf get-socket): Private generic functions
(setf get-timeout): Private generic functions
(setf get-timeout): Private generic functions
(setf get-timestamp): Private generic functions
(setf get-timestamp): Private generic functions

C
cleanup-old-connections: Private generic functions
cleanup-old-connections: Private generic functions
close-all-connections: Public ordinary functions
close-all-connections-internal: Private generic functions
close-all-connections-internal: Private generic functions
close-connection: Private ordinary functions
concatenate-chunks: Private ordinary functions

D
do-http-request: Public ordinary functions
do-http-request-internal: Private ordinary functions
do-one-request-response: Private ordinary functions

E
encode-basic-authorization: Private ordinary functions

F
format-http-request-line: Private ordinary functions
Function, close-all-connections: Public ordinary functions
Function, close-connection: Private ordinary functions
Function, concatenate-chunks: Private ordinary functions
Function, do-http-request: Public ordinary functions
Function, do-http-request-internal: Private ordinary functions
Function, do-one-request-response: Private ordinary functions
Function, encode-basic-authorization: Private ordinary functions
Function, format-http-request-line: Private ordinary functions
Function, get-open-connection: Private ordinary functions
Function, gunzip: Private ordinary functions
Function, header-field-name->keyword: Private ordinary functions
Function, header-field-value->string: Private ordinary functions
Function, make-http-client-state: Public ordinary functions
Function, open-socket-stream: Private ordinary functions
Function, read-crlf-line: Private ordinary functions
Function, read-response: Private ordinary functions
Function, release-connection: Private ordinary functions
Function, response-read-body: Private ordinary functions
Function, response-read-chunked-body: Private ordinary functions
Function, response-read-code: Private ordinary functions
Function, response-read-headers: Private ordinary functions
Function, response-read-undefined-body: Private ordinary functions
Function, uri-decode-for-query: Public ordinary functions
Function, uri-encode-for-query: Public ordinary functions
Function, write-http-request-line: Private ordinary functions
Function, write-request: Private ordinary functions

G
Generic Function, (setf get-buffer): Private generic functions
Generic Function, (setf get-endpoint): Private generic functions
Generic Function, (setf get-in-use-p): Private generic functions
Generic Function, (setf get-scheme-host-port): Private generic functions
Generic Function, (setf get-socket): Private generic functions
Generic Function, (setf get-timeout): Private generic functions
Generic Function, (setf get-timestamp): Private generic functions
Generic Function, cleanup-old-connections: Private generic functions
Generic Function, close-all-connections-internal: Private generic functions
Generic Function, get-buffer: Private generic functions
Generic Function, get-endpoint: Private generic functions
Generic Function, get-http-server-state: Private generic functions
Generic Function, get-in-use-p: Private generic functions
Generic Function, get-kept-alive-age: Private generic functions
Generic Function, get-lock: Private generic functions
Generic Function, get-scheme-host-port: Private generic functions
Generic Function, get-socket: Private generic functions
Generic Function, get-timeout: Private generic functions
Generic Function, get-timestamp: Private generic functions
get-buffer: Private generic functions
get-buffer: Private generic functions
get-endpoint: Private generic functions
get-endpoint: Private generic functions
get-http-server-state: Private generic functions
get-http-server-state: Private generic functions
get-in-use-p: Private generic functions
get-in-use-p: Private generic functions
get-kept-alive-age: Private generic functions
get-kept-alive-age: Private generic functions
get-lock: Private generic functions
get-lock: Private generic functions
get-open-connection: Private ordinary functions
get-scheme-host-port: Private generic functions
get-scheme-host-port: Private generic functions
get-socket: Private generic functions
get-socket: Private generic functions
get-timeout: Private generic functions
get-timeout: Private generic functions
get-timestamp: Private generic functions
get-timestamp: Private generic functions
gunzip: Private ordinary functions

H
header-field-name->keyword: Private ordinary functions
header-field-value->string: Private ordinary functions

M
make-http-client-state: Public ordinary functions
Method, (setf get-buffer): Private generic functions
Method, (setf get-endpoint): Private generic functions
Method, (setf get-in-use-p): Private generic functions
Method, (setf get-scheme-host-port): Private generic functions
Method, (setf get-socket): Private generic functions
Method, (setf get-timeout): Private generic functions
Method, (setf get-timestamp): Private generic functions
Method, cleanup-old-connections: Private generic functions
Method, close-all-connections-internal: Private generic functions
Method, get-buffer: Private generic functions
Method, get-endpoint: Private generic functions
Method, get-http-server-state: Private generic functions
Method, get-in-use-p: Private generic functions
Method, get-kept-alive-age: Private generic functions
Method, get-lock: Private generic functions
Method, get-scheme-host-port: Private generic functions
Method, get-socket: Private generic functions
Method, get-timeout: Private generic functions
Method, get-timestamp: Private generic functions
Method, print-object: Public standalone methods

O
open-socket-stream: Private ordinary functions

P
print-object: Public standalone methods

R
read-crlf-line: Private ordinary functions
read-response: Private ordinary functions
release-connection: Private ordinary functions
response-read-body: Private ordinary functions
response-read-chunked-body: Private ordinary functions
response-read-code: Private ordinary functions
response-read-headers: Private ordinary functions
response-read-undefined-body: Private ordinary functions

U
uri-decode-for-query: Public ordinary functions
uri-encode-for-query: Public ordinary functions

W
write-http-request-line: Private ordinary functions
write-request: Private ordinary functions


A.3 Variables

Jump to:   *   +  
B   D   E   I   L   S   T  
Index Entry  Section

*
*connection-keep-alive-timeout*: Private special variables
*default-http-client-state*: Public special variables
*endpoint*: Private special variables
*http-client-accept*: Public special variables
*http-client-accept-encoding*: Public special variables
*http-client-agent*: Public special variables

+
+common-response-headers+: Private special variables
+uri-encode-char-map+: Private special variables

B
buffer: Private classes

D
data: Public classes

E
endpoint: Private conditions

I
in-use-p: Private classes

L
lock: Public classes

S
scheme-host-port: Private classes
Slot, buffer: Private classes
Slot, data: Public classes
Slot, endpoint: Private conditions
Slot, in-use-p: Private classes
Slot, lock: Public classes
Slot, scheme-host-port: Private classes
Slot, socket: Private classes
Slot, timeout: Private conditions
Slot, timestamp: Private classes
socket: Private classes
Special Variable, *connection-keep-alive-timeout*: Private special variables
Special Variable, *default-http-client-state*: Public special variables
Special Variable, *endpoint*: Private special variables
Special Variable, *http-client-accept*: Public special variables
Special Variable, *http-client-accept-encoding*: Public special variables
Special Variable, *http-client-agent*: Public special variables
Special Variable, +common-response-headers+: Private special variables
Special Variable, +uri-encode-char-map+: Private special variables

T
timeout: Private conditions
timestamp: Private classes