icapclient

README

icap-client

Talk to the ICAP servers using probably the first ICAP client package in GO!

Installing

go get -u github.com/egirna/icap-client

Usage

Import The Package

import ic "github.com/egirna/icap-client"

Making a simple RESPMOD call

  req, err := ic.NewRequest(ic.MethodRESPMOD, "icap://<host>:<port>/<path>", httpReq, httpResp)

  if err != nil {
    log.Fatal(err)
  }

  client := &ic.Client{
		Timeout: 5 * time.Second,
	}

  resp, err := client.Do(req)

	if err != nil {
		log.Fatal(err)
	}

Note: httpReq & httpResp here are *http.Response & *http.Request respectively

Setting preview obtained from OPTIONS call

  optReq, err := ic.NewRequest(ic.MethodOPTIONS, "icap://<host>:<port>/<path>", nil, nil)

  if err != nil {
    log.Fatal(err)
    return
  }

  client := &ic.Client{
    Timeout: 5 * time.Second,
  }

  req.SetPreview(optReq.PreviewBytes)

  // do something with req(ICAP *Request)

DEBUG Mode

Turn on debug mode to inspect detailed & verbose logs to debug your code during development

  ic.SetDebugMode(true)

By default the icap-client will dump the debugging logs to the standard output(stdout), but you can always add your custom writer

  f, _ := os.OpenFile("logs.txt", os.O_RDWR|os.O_CREATE|os.O_APPEND, 0666)
  ic.SetDebugOutput(f)

For more details, see the docs and examples.

Contributing

This package is still WIP, so totally open to suggestions. See the contributions guide here.

License

icap-client is licensed under the Apache License.

Documentation

Overview

Package icapclient is a client package for the ICAP protocol

Here is a basic example:

 package main

 import (
	  "fmt"
	  "log"
	  "net/http"
	  "time"

	  ic "github.com/egirna/icap-client"
 )

 func main() {
  /* preparing the http request required for the RESPMOD */
	 httpReq, err := http.NewRequest(http.MethodGet, "http://localhost:8000/sample.pdf", nil)

	 if err != nil {
	  	log.Fatal(err)
	 }

  /* making the http client & making the request call to get the response needed for the icap RESPMOD call */
	 httpClient := &http.Client{}

	 httpResp, err := httpClient.Do(httpReq)

	 if err != nil {
		 log.Fatal(err)
	 }

  /* making a icap request with OPTIONS method */
	 optReq, err := ic.NewRequest(ic.MethodOPTIONS, "icap://127.0.0.1:1344/respmod", nil, nil)

	 if err != nil {
		 log.Fatal(err)
		 return
	 }

  /* making the icap client responsible for making the requests */
	 client := &ic.Client{
		 Timeout: 5 * time.Second,
	 }

  /* making the OPTIONS request call */
	 optResp, err := client.Do(optReq)

	 if err != nil {
		 log.Fatal(err)
		 return
	 }

  /* making a icap request with RESPMOD method */
	 req, err := ic.NewRequest(ic.MethodRESPMOD, "icap://127.0.0.1:1344/respmod", httpReq, httpResp)

	 if err != nil {
		 log.Fatal(err)
	 }

	 req.SetPreview(optResp.PreviewBytes) // setting the preview bytes obtained from the OPTIONS call

  /* making the RESPMOD request call */
	 resp, err := client.Do(req)

	 if err != nil {
		 log.Fatal(err)
	 }

	 fmt.Println(resp.StatusCode)

 }

See https://github.com/egirna/icap-client/examples.

Index

• Constants
• Variables
• func DumpRequest(req *Request) ([]byte, error)
• func NewChunkedWriter(w io.Writer) io.WriteCloser
• func SetDebugMode(debug bool)
• func SetDebugOutput(w io.Writer)
• type Client
  • func (c *Client) Do(req *Request) (*Response, error)
  • func (c *Client) DoRemaining(req *Request) (*Response, error)
  • func (c *Client) SetDriver(d *Driver)
• type Driver
  • func NewDriver(host string, port int) *Driver
  • func (d *Driver) Close() error
  • func (d *Driver) Connect() error
  • func (d *Driver) ConnectWithContext(ctx context.Context) error
  • func (d *Driver) Receive() (*Response, error)
  • func (d *Driver) Send(data []byte) error
  • func (d *Driver) TlSDial() error
• type Request
  • func NewRequest(method, urlStr string, httpReq *http.Request, httpResp *http.Response) (*Request, error)
  • func NewRequestTLS(method, urlStr string, httpReq *http.Request, httpResp *http.Response, ...) (*Request, error)
  • func (r *Request) ExtendHeader(hdr http.Header) error
  • func (r *Request) SetContext(ctx context.Context)
  • func (r *Request) SetDefaultRequestHeaders()
  • func (r *Request) SetPreview(maxBytes int) error
  • func (r *Request) Validate() error
• type Response
  • func ReadRespons(b *bufio.ReadWriter) (resp *Response, err error)
• type Responseold

Constants

const (
	MethodOPTIONS = "OPTIONS"
	MethodRESPMOD = "RESPMOD"
	MethodREQMOD  = "REQMOD"
)

the icap request methods

const (
	ErrInvalidScheme       = "the url scheme must be icap://"
	ErrMethodNotRegistered = "the requested method is not registered"
	ErrInvalidHost         = "the requested host is invalid"
	ErrConnectionNotOpen   = "no open connection to close"
	ErrInvalidTCPMsg       = "invalid tcp message"
	ErrREQMODWithNoReq     = "http request cannot be nil for method REQMOD"
	ErrREQMODWithResp      = "http response must be nil for method REQMOD"
	ErrRESPMODWithNoResp   = "http response cannot be nil for method RESPMOD"
)

the error messages

const (
	SchemeICAP     = "icap"
	ICAPVersion    = "ICAP/1.0"
	HTTPVersion    = "HTTP/1.1"
	SchemeHTTPReq  = "http_request"
	SchemeHTTPResp = "http_response"
	CRLF           = "\r\n"
	DoubleCRLF     = "\r\n\r\n"
	LF             = "\n"
)

general constants required for the package

const (
	PreviewHeader          = "Preview"
	MethodsHeader          = "Methods"
	AllowHeader            = "Allow"
	EncapsulatedHeader     = "Encapsulated"
	TransferPreviewHeader  = "Transfer-Preview"
	ServiceHeader          = "Service"
	ISTagHeader            = "ISTag"
	OptBodyTypeHeader      = "Opt-body-type"
	MaxConnectionsHeader   = "Max-Connections"
	OptionsTTLHeader       = "Options-TTL"
	ServiceIDHeader        = "Service-ID"
	TransferIgnoreHeader   = "Transfer-Ignore"
	TransferCompleteHeader = "Transfer-Complete"
)

Common ICAP headers

Variables

var (
	DEBUG = false
)

the debug mode determiner & the writer to the write the debug output to

Functions

func DumpRequest

func DumpRequest(req *Request) ([]byte, error)

DumpRequest returns the given request in its ICAP/1.x wire representation.

func NewChunkedWriter

func NewChunkedWriter(w io.Writer) io.WriteCloser

NewChunkedWriter returns a new chunkedWriter that translates writes into HTTP "chunked" format before writing them to w. Closing the returned chunkedWriter sends the final 0-length chunk that marks the end of the stream.

NewChunkedWriter is not needed by normal applications. The http package adds chunking automatically if handlers don't set a Content-Length header. Using NewChunkedWriter inside a handler would result in double chunking or chunking with a Content-Length length, both of which are wrong.

func SetDebugMode

func SetDebugMode(debug bool)

SetDebugMode sets the debug mode for the entire package depending on the bool

func SetDebugOutput

func SetDebugOutput(w io.Writer)

SetDebugOutput sets writer to write the debug outputs (default: os.Stdout)

Types

type Client

type Client struct {
	Timeout time.Duration
	// contains filtered or unexported fields
}

Client represents the icap client who makes the icap server calls

func (*Client) Do

func (c *Client) Do(req *Request) (*Response, error)

Do makes does everything required to make a call to the ICAP server

func (*Client) DoRemaining

func (c *Client) DoRemaining(req *Request) (*Response, error)

DoRemaining requests an ICAP server with the remaining body bytes which did not fit in the preview in the original request

func (*Client) SetDriver

func (c *Client) SetDriver(d *Driver)

SetDriver sets a new socket driver with the client

type Driver

type Driver struct {
	Host          string
	Port          int
	DialerTimeout time.Duration
	ReadTimeout   time.Duration
	WriteTimeout  time.Duration
	// contains filtered or unexported fields
}

Driver os the one responsible for driving the transport layer operations

func NewDriver

func NewDriver(host string, port int) *Driver

NewDriver is the factory function for Driver

func (*Driver) Close

func (d *Driver) Close() error

Close closes the socket connection

func (*Driver) Connect

func (d *Driver) Connect() error

Connect fires up a tcp socket connection with the icap server

func (*Driver) ConnectWithContext

func (d *Driver) ConnectWithContext(ctx context.Context) error

ConnectWithContext connects to the server satisfying the context

func (*Driver) Receive

func (d *Driver) Receive() (*Response, error)

Receive returns the respone from the tcp socket connection

func (*Driver) Send

func (d *Driver) Send(data []byte) error

Send sends a request to the icap server

func (*Driver) TlSDial

func (d *Driver) TlSDial() error

TlSDial Connecting with a custom root-certificate set.

type Request

type Request struct {
	Method       string
	URL          *url.URL
	Header       http.Header
	HTTPRequest  *http.Request
	HTTPResponse *http.Response
	ChunkLength  int
	PreviewBytes int

	ConnType string
	// contains filtered or unexported fields
}

Request represents the icap client request data

func NewRequest

func NewRequest(method, urlStr string, httpReq *http.Request, httpResp *http.Response) (*Request, error)

NewRequest is the factory function for Request

func NewRequestTLS

func NewRequestTLS(method, urlStr string, httpReq *http.Request, httpResp *http.Response, conntype string) (*Request, error)

NewRequestTLS is the factory function for Request

func (*Request) ExtendHeader

func (r *Request) ExtendHeader(hdr http.Header) error

ExtendHeader extends the current ICAP Request header with a new header

func (*Request) SetContext

func (r *Request) SetContext(ctx context.Context)

SetContext sets a context for the ICAP request

func (*Request) SetDefaultRequestHeaders

func (r *Request) SetDefaultRequestHeaders()

SetDefaultRequestHeaders assigns some of the headers with its default value if they are not set already

func (*Request) SetPreview

func (r *Request) SetPreview(maxBytes int) error

SetPreview sets the preview bytes in the icap header

func (*Request) Validate

func (r *Request) Validate() error

Validate validates the ICAP request

type Response

type Response struct {
	Method       string               // REQMOD, RESPMOD, OPTIONS, etc.
	RawURL       string               // The URL given in the request.
	URL          *url.URL             // Parsed URL.
	Proto        string               // The protocol version.
	Header       textproto.MIMEHeader // The ICAP header
	RemoteAddr   string               // the address of the computer sending the request
	Preview      []byte               // the body data for an ICAP preview
	StatusCode   int
	Status       string
	PreviewBytes int
	// The HTTP messages.
	Body            []byte
	ContentRequest  *http.Request
	ContentResponse *http.Response
}

Response represents a parsed ICAP request.

func ReadRespons

func ReadRespons(b *bufio.ReadWriter) (resp *Response, err error)

ReadRespons chunked

type Responseold

type Responseold struct {
	StatusCode      int
	Status          string
	PreviewBytes    int
	Header          textproto.MIMEHeader
	ContentRequest  *http.Request
	ContentResponse *http.Response
}

Response represents the icap server response data