icapclient

README

icap-client

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

Installing

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

Usage

Import The Package

import ic "github.com/integrationworks/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 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
• type Request
  • func NewRequest(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 ReadResponse(b *bufio.Reader) (*Response, error)

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 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

type Request

type Request struct {
	Method       string
	URL          *url.URL
	Header       http.Header
	HTTPRequest  *http.Request
	HTTPResponse *http.Response
	ChunkLength  int
	PreviewBytes int
	// 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 (*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 {
	StatusCode      int
	Status          string
	PreviewBytes    int
	Header          http.Header
	ContentRequest  *http.Request
	ContentResponse *http.Response
}

Response represents the icap server response data

func ReadResponse

func ReadResponse(b *bufio.Reader) (*Response, error)

ReadResponse converts a Reader to a icapclient Response