persistentconn

README

splunk-persistentconn

splunk-persistentconn implements the protocol that splunk core uses to communicate with persistent script that's used to power REST endpoints of an app

How to use

Usage example:

package main

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

    conn "github.com/DrakeW/splunk-persistentconn"
)

func main() {
    // server initialization
    server := conn.NewServer()

    // register endpoint using either static path or path pattern
    server.Handle("entity/:id/data", func(req conn.Request) (conn.Response, error) {
        return conn.Response{
            StatusCode: http.StatusOK,
            Body:       fmt.Sprintf("hello world %s", req.Params["id"]),
        }, nil
    }, "GET", "POST")

    // starts server
    server.Run()
}

An example app is located in the examples directory.

Performance

This package is built to take advantage of the concurrent processing capability provided by goroutines for each handler registered. However, since Splunk core sends requests to the server process in a synchronous manner, only one goroutine is spawned at a time therefore currently there's no performance boost.

Based on rough benchmark with the same 5000 non-blocking requests (where each request takes ~0.5s to finish) hitting both the python REST endpoint based on PersistentServerConnectionApplication and the Go REST endpoint using the splunk-persistentconn package, performance is roughly the same.

Disclaimer

This package is not officially supported by Splunk. Please use with caution and feel free to open issue or PR for any kind of bug report or feature enhancement.

Documentation

Overview

Package persistentconn implements the persistent script protocol that splunk core uses to communicate with app's persistent REST endpoint. This package handles basic routing and request/response handling.

Index

• Constants
• type Handler
• type Request
• type RequestPacket
  • func ReadPacket(reader io.Reader) (*RequestPacket, error)
• type Response
  • func NoMatchingHandler(re Request) (Response, error)
• type Server
  • func NewServer() *Server
  • func (s *Server) Handle(path string, handler Handler, allowedMethods ...string)
  • func (s *Server) Run()

Constants

const (
	// OPCODE_REQUEST_INIT is a bit mask that's used to verify if request is the first request
	OPCODE_REQUEST_INIT = 0x01
	// OPCODE_REQUEST_BLOCK is a bit mask that's used to verify if request contains input block
	OPCODE_REQUEST_BLOCK = 0x02
	// OPCODE_REQUEST_END is a bit mask that's used to verify if request is the end
	OPCODE_REQUEST_END = 0x04
	// OPCODE_REQUEST_ALLOW_STREAM is a bit mask that's used to verify if request indicates streaming handler is allowed
	OPCODE_REQUEST_ALLOW_STREAM = 0x08
)

Types

type Handler

type Handler func(Request) (Response, error)

Handler is a handler function that takes a persistentconn request and returns a response or error if error is returned, the server will return a 500 (Internal Server Error) response with the returned error's message as the response body

type Request

type Request struct {
	OutputMode string            `json:"output_mode"`
	Headers    map[string]string `json:"headers"`
	Method     string            `json:"method"`
	Namespace  struct {
		App  string `json:"app"`
		User string `json:"user"`
	} `json:"namespace"`
	Session struct {
		User      string `json:"user"`
		Authtoken string `json:"authtoken"`
	} `json:"session"`
	Query   map[string]string `json:"query"`
	Form    map[string]string `json:"form,omitempty"`
	Payload string            `json:"payload,omitempty"`
	Path    string            `json:"path"`
	Params  map[string]string `json:"params,omitempty"`
	// contains filtered or unexported fields
}

Request contains information of an incoming request

type RequestPacket

type RequestPacket struct {
	// contains filtered or unexported fields
}

RequestPacket object representing a received packet

func ReadPacket

func ReadPacket(reader io.Reader) (*RequestPacket, error)

ReadPacket creates a packet based on input and communication protocol set by splunkd.

type Response

type Response struct {
	StatusCode int    `json:"status"`
	Body       string `json:"payload"`
	// contains filtered or unexported fields
}

Response represents the response sent back to the client

func NoMatchingHandler

func NoMatchingHandler(re Request) (Response, error)

NoMatchingHandler is the default handler returned when no matching path is found from a request

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server represents the persistentconn server that handles request and writes response back to the client

func NewServer

func NewServer() *Server

NewServer creates a persistentconn server

func (*Server) Handle

func (s *Server) Handle(path string, handler Handler, allowedMethods ...string)

Handle registers a handler function for a given path (or path pattern). A path pattern is in the format of "<component>/:<param_1>/<component>/..." and a path component starting with ":" indicates it's a parameter which will be inferred from the actual path in the request E.g. if the registered path pattern is "entity/:name/data" and the path in the request is "entity/hello/data", then the key-value pair {"name": "hello"} will be stored in the request's params which can be later referenced inside of the handler.

func (*Server) Run

func (s *Server) Run()

Run starts a persistentconn server and starts handling request sent from client (with splunkd as the middle layer)