socketmap

README

Go implementation for Postfix' socketmap_table lookup protocol

Package socketmap implements Postfix' socketmap_table lookup protocol.

Background

The Postfix mail server uses lookup tables in various places, when it needs to translate some value into another. The most common use case is alias expansion for mail addresses.

While most tasks can be achieved using Postfix' built-in tables and flat files, sometimes, a more dynamic approach is needed. Therefore, Postfix can query external services using the socketmap_table protocol.

Implementing a lookup server

To implement a socketmap_table lookup server, only two things are needed:

1. A lookup function which implements the lookup itself and returns a response
2. A network listener to listen for Postfix' connections on

The source code repository has examples.

A single server can handle many different named maps, by registering different lookup functions.

Origin and maintenance

This package was written for the Bergblau component WebMilterd, which, among otehr functionality, resolves aliases by querying a REST API.

It is maintained by velocitux, which also offers commercial support for this lookup mechanism and for Postfix in general.

Documentation

Overview

Package socketmap implements Postfix' socketmap_table lookup protocol.

Background

The Postfix mail server uses lookup tables in various places, when it needs to translate some value into another. The most common use case is alias expansion for mail addresses.

While most tasks can be achieved using Postfix' built-in tables and flat files, sometimes, a more dynamic approach is needed. Therefore, Postfix can query external services using the socketmap_table protocol.

Implementing a lookup server

To implement a socketmap_table lookup server, only two things are needed:

1. A lookup function with the signature of LookupFn which implements the lookup itself and returns a response
2. A network net.Listener to listen for Postfix' connections on

The source code repository has examples.

A single server can handle many different named maps, by registering different lookup functions with the SocketMapServer.RegisterMap function.

Index

• type LookupFn
• type SocketMapRequest
  • func (r *SocketMapRequest) Decode(ns *netstring.Netstring) error
• type SocketMapResult
  • func NotFound() *SocketMapResult
  • func Ok(data string) *SocketMapResult
  • func PermFail(reason string) *SocketMapResult
  • func TempFail(reason string) *SocketMapResult
  • func Timeout(reason string) *SocketMapResult
  • func (r *SocketMapResult) Encode() *netstring.Netstring
• type SocketMapServer
  • func NewSocketMapServer() *SocketMapServer
  • func (s *SocketMapServer) RegisterMap(name string, fn LookupFn)
  • func (s *SocketMapServer) Serve(listener net.Listener) error

Types

type LookupFn

type LookupFn func(key string) (*SocketMapResult, error)

Lookup function called by the SocketMapServer for each request to the map it is registered for

type SocketMapRequest

type SocketMapRequest struct {
	Name string
	Key  string
}

A request as received from Postfix

func (*SocketMapRequest) Decode

func (r *SocketMapRequest) Decode(ns *netstring.Netstring) error

Decode the request from a netstring object after deserialization

type SocketMapResult

type SocketMapResult struct {
	Status string
	Data   string
}

A result sent to Postfix

func NotFound

func NotFound() *SocketMapResult

Produce a NOTFOUND response

func Ok

func Ok(data string) *SocketMapResult

Produce an OK response

func PermFail

func PermFail(reason string) *SocketMapResult

Produce a PERM response

func TempFail

func TempFail(reason string) *SocketMapResult

Produce a TEMP response

func Timeout

func Timeout(reason string) *SocketMapResult

Produce a TIMEOUT response

func (*SocketMapResult) Encode

func (r *SocketMapResult) Encode() *netstring.Netstring

Encode the result into a netstring object for further serialization

type SocketMapServer

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

A server handling socketmap_table connections on one network listener

func NewSocketMapServer

func NewSocketMapServer() *SocketMapServer

Create a new SocketMapServer with an empty mapping map

func (*SocketMapServer) RegisterMap

func (s *SocketMapServer) RegisterMap(name string, fn LookupFn)

Register a lookup function as a named map The map name is sent by Postfix, according to its configuration.

func (*SocketMapServer) Serve

func (s *SocketMapServer) Serve(listener net.Listener) error

Register a lookup function as a named map The map name is sent by Postfix, according to its configuration.