listener

README

Listener Library

This library aims to speed up setting up listeners by removing the need to write boiler plate code all the time. This is a somewhat opiniated library with some assumptions made for how things should be structured. It does not however, stop you from writing your own handlers to process the request, that part is entirely up to you, the developer.

Currently, only the REST is implemented. TCP, UDP and MQTT support will be added when the time and need permits.

Documentation

Guides on how to use the library is explained the docs folder, which contains documentation for each of the listener

1. REST
2. Unix Socket

Documentation

Overview

Copyright © 2024 Vicknesh Suppramaniam <vicknesh@handletec.my>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright © 2024 Vicknesh Suppramaniam <vicknesh@handletec.my>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright © 2024 Vicknesh Suppramaniam <vicknesh@handletec.my>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright © 2024 Vicknesh Suppramaniam <vicknesh@handletec.my>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright © 2024 Vicknesh Suppramaniam <vicknesh@handletec.my>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software provided under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• type Listener
• type Listeners
  • func (ls *Listeners) Add(l Listener) (err error)
  • func (ls Listeners) StartAll() (err error)
  • func (ls Listeners) String() (str string)
• type Protocol
  • func ParseProto(protoStr string) (proto Protocol)
  • func (proto Protocol) IsValid() (valid bool)
  • func (proto Protocol) Listener() (l Listener, err error)
  • func (proto Protocol) String() (str string)
• type TLSClientAuth
  • func (tca TLSClientAuth) AuthType() (at tls.ClientAuthType)
  • func (tca TLSClientAuth) String() (str string)
• type TLSConfigBuilder
  • func NewTLSConfigBuilder(useSystemCA bool) (*TLSConfigBuilder, error)
  • func (t *TLSConfigBuilder) AddCABytes(pemData []byte) error
  • func (t *TLSConfigBuilder) AddCADir(dir string) error
  • func (t *TLSConfigBuilder) AddCAFile(path string) error
  • func (t *TLSConfigBuilder) Close()
  • func (t *TLSConfigBuilder) FileExists(path string) error
  • func (t *TLSConfigBuilder) ForClient() *tls.Config
  • func (t *TLSConfigBuilder) ForServer() *tls.Config
  • func (t *TLSConfigBuilder) SetCertKeyFile(certPath, keyPath string) error
  • func (t *TLSConfigBuilder) SetCertKeyFromBytes(certPEM, keyPEM []byte) error
  • func (t *TLSConfigBuilder) SetClientAuth(auth TLSClientAuth)
  • func (t *TLSConfigBuilder) SetInsecureSkipVerify(skip bool)
  • func (t *TLSConfigBuilder) VerifyCertTrusted(certPEM []byte) error

Types

type Listener

type Listener interface {
	Name() string
	Init(logger *slog.Logger, address string, port int, tlsConfig *tls.Config) error
	SetConfig(config any) error
	Start() error
}

Listener - generic interface that specific interfaces must implement

type Listeners

type Listeners []Listener

Listeners - slice of listeners for specific protocols

func (*Listeners) Add

func (ls *Listeners) Add(l Listener) (err error)

Add - add a protocol to the listeners type

func (Listeners) StartAll

func (ls Listeners) StartAll() (err error)

StartAll - start all configured listeners

func (Listeners) String

func (ls Listeners) String() (str string)

type Protocol

type Protocol uint8

Protocol - custom protocol definitions

const (
	ProtoNone Protocol = iota
	ProtoREST
	ProtoUnixSocket
)

func ParseProto

func ParseProto(protoStr string) (proto Protocol)

ParseProto - returns protocol type from given string

func (Protocol) IsValid

func (proto Protocol) IsValid() (valid bool)

IsValid - determines if a valid protocol is given

func (Protocol) Listener

func (proto Protocol) Listener() (l Listener, err error)

Listener - returns listener implementation for this protocol

func (Protocol) String

func (proto Protocol) String() (str string)

type TLSClientAuth

type TLSClientAuth tls.ClientAuthType

TLSClientAuth - TLS client authentication type

const (
	// TLSClientAuthNone - there is no need to verify clients
	TLSClientAuthNone TLSClientAuth = TLSClientAuth(tls.NoClientCert)

	// TLSClientAuthRequest - server may request client cert but clients are not obligated to send it
	TLSClientAuthRequest TLSClientAuth = TLSClientAuth(tls.RequestClientCert)

	// TLSClientAuthRequire - clients should send a certificate however the cert does not need to be valid
	TLSClientAuthRequire TLSClientAuth = TLSClientAuth(tls.RequireAnyClientCert)

	// TLSClientAuthVerify - server may request client cert and if client responds, the cert must be valid
	TLSClientAuthVerify TLSClientAuth = TLSClientAuth(tls.VerifyClientCertIfGiven)

	// TLSClientAuthRequireVerify - server requests client cert and the client **MUST** respond with a valid certificate
	TLSClientAuthRequireVerify TLSClientAuth = TLSClientAuth(tls.RequireAndVerifyClientCert)
)

func (TLSClientAuth) AuthType

func (tca TLSClientAuth) AuthType() (at tls.ClientAuthType)

func (TLSClientAuth) String

func (tca TLSClientAuth) String() (str string)

type TLSConfigBuilder

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

TLSConfigBuilder - builds and manages tls.Config instances for both server and client.

func NewTLSConfigBuilder

func NewTLSConfigBuilder(useSystemCA bool) (*TLSConfigBuilder, error)

NewTLSConfigBuilder - creates a new TLSConfigBuilder. If useSystemCA is true, it loads system root CAs.

func (*TLSConfigBuilder) AddCABytes

func (t *TLSConfigBuilder) AddCABytes(pemData []byte) error

AddCABytes - adds PEM-encoded certificates to the CA pool.

func (*TLSConfigBuilder) AddCADir

func (t *TLSConfigBuilder) AddCADir(dir string) error

AddCADir - loads all .crt/.pem files in a directory into the CA pool.

func (*TLSConfigBuilder) AddCAFile

func (t *TLSConfigBuilder) AddCAFile(path string) error

AddCAFile - loads a CA certificate from file and adds it to the pool.

func (*TLSConfigBuilder) Close

func (t *TLSConfigBuilder) Close()

Close - stops file watching.

func (*TLSConfigBuilder) FileExists

func (t *TLSConfigBuilder) FileExists(path string) error

FileExists - checks if the given path exists and is a regular file.

func (*TLSConfigBuilder) ForClient

func (t *TLSConfigBuilder) ForClient() *tls.Config

ForClient - returns a configured *tls.Config for client usage.

func (*TLSConfigBuilder) ForServer

func (t *TLSConfigBuilder) ForServer() *tls.Config

ForServer - returns a configured *tls.Config for server usage.

func (*TLSConfigBuilder) SetCertKeyFile

func (t *TLSConfigBuilder) SetCertKeyFile(certPath, keyPath string) error

SetCertKeyFile - sets the cert and key files.

func (*TLSConfigBuilder) SetCertKeyFromBytes

func (t *TLSConfigBuilder) SetCertKeyFromBytes(certPEM, keyPEM []byte) error

SetCertKeyFromBytes - sets the cert and key directly from memory.

func (*TLSConfigBuilder) SetClientAuth

func (t *TLSConfigBuilder) SetClientAuth(auth TLSClientAuth)

SetClientAuth - sets the desired client auth level.

func (*TLSConfigBuilder) SetInsecureSkipVerify

func (t *TLSConfigBuilder) SetInsecureSkipVerify(skip bool)

SetInsecureSkipVerify - enables or disables skipping TLS verification (for testing).

func (*TLSConfigBuilder) VerifyCertTrusted

func (t *TLSConfigBuilder) VerifyCertTrusted(certPEM []byte) error

VerifyCertTrusted - checks if a given PEM cert is trusted by the internal CA pool.