mtx

package module
v0.0.0-...-3568ea4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 12, 2026 License: MIT Imports: 13 Imported by: 0

README

mtx

CI Status codecov Go Report Card CodeQL Go Reference License Go Version Release

Template repository for standing up Go library infrastructure matching the zoobzio ecosystem. Clone it, rename it, start building.

What's Included

your-new-package/
├── go.mod                    # Go 1.24+ with toolchain
├── Makefile                  # test, lint, coverage, ci targets
├── .golangci.yml             # v2 config with security linters
├── .codecov.yml              # 70% project / 80% patch targets
├── .goreleaser.yml           # Library release automation
├── .github/workflows/
│   ├── ci.yml                # Test matrix, lint, security, benchmarks
│   ├── coverage.yml          # Codecov integration
│   ├── release.yml           # Tag-triggered releases
│   └── codeql.yml            # Weekly security analysis
├── testing/
│   ├── helpers.go            # Reusable test utilities
│   ├── integration/          # Integration test structure
│   └── benchmarks/           # Benchmark structure
├── LICENSE                   # MIT
├── CONTRIBUTING.md           # Development workflow
└── SECURITY.md               # Vulnerability reporting

Install

This is a GitHub template repository. Click Use this template on GitHub, or:

gh repo create your-package --template zoobzio/mtx --clone
cd your-package

Then update go.mod, Makefile, and .goreleaser.yml with your package name.

Quick Start

After creating your repository from the template:

# Update module path
sed -i 's/mtx/your-package/g' go.mod Makefile .goreleaser.yml

# Install development tools
make install-tools

# Verify everything works
make check

# Start building

Capabilities

Feature Description Configuration
Multi-version testing Go 1.24 and 1.25 matrix .github/workflows/ci.yml
Linting golangci-lint v2 with security focus .golangci.yml
Coverage tracking Codecov with PR comments .codecov.yml
Release automation GoReleaser for library packages .goreleaser.yml
Security scanning gosec + CodeQL .github/workflows/codeql.yml
Benchmarks Structured benchmark directory testing/benchmarks/

Why mtx?

  • Immediate CI: Push and your workflows run—no setup required
  • Consistent tooling: Every zoobzio package uses the same linter config, coverage targets, and release process
  • Security by default: gosec, CodeQL, and security-focused linters enabled from day one
  • Test infrastructure ready: Helpers, integration tests, and benchmarks structured and waiting

The Zoobzio Ecosystem

All zoobzio Go libraries use mtx as their foundation. When standards evolve, updates propagate from here.

Documentation

  • Learn: Review the configuration files directly—they're documented inline
  • Guides: See CONTRIBUTING.md for development workflow
  • Reference: Run make help for available commands

Contributing

Development workflow and conventions are documented in CONTRIBUTING.md.

License

MIT License - see LICENSE

Documentation

Overview

Package mtx provides a standalone Matrix messaging CLI for agentic coordination.

Index

Constants

This section is empty.

Variables

View Source 
var (
	Homeserver string
)

Package-level config set via PersistentPreRunE from the loaded Config.

Functions

func Execute 

func Execute() error

Execute runs the root command.

func ResolveRoomID 

func ResolveRoomID(arg string, resolve AliasResolver) (string, error)

ResolveRoomID resolves a room argument that may be a room ID, full alias, or short alias name into a room ID.

func ServerName 

func ServerName(homeserver string) string

ServerName extracts the hostname from a homeserver URL.

func TokenFromEnv 

func TokenFromEnv() (string, error)

TokenFromEnv reads the Matrix access token. It checks MTX_TOKEN first, then walks up from CWD looking for .mtx/env files.

Types

type AliasResolver 

type AliasResolver func(alias string) (*AliasResponse, error)

AliasResolver resolves a room alias to a room ID.

type AliasResponse 

type AliasResponse struct {
	RoomID  string   `json:"room_id"`
	Servers []string `json:"servers"`
}

AliasResponse is returned when resolving a room alias.

type Authenticator 

type Authenticator func(username, password string) (*Registration, error)

Authenticator logs into a Matrix account.

type Client 

type Client struct {
	HTTP        *http.Client
	Homeserver  string
	AccessToken string
}

Client performs HTTP requests against a Matrix homeserver.

func NewClient 

func NewClient(homeserver, accessToken string) *Client

NewClient creates a Matrix client for the given homeserver and access token.

func (*Client) CreateDMRoom 

func (c *Client) CreateDMRoom(invite string) (*Room, error)

CreateDMRoom creates a direct-message room and invites the target user. Uses trusted_private_chat preset so the invited user can join immediately.

func (*Client) CreateRoom 

func (c *Client) CreateRoom(name, topic string) (*Room, error)

CreateRoom creates a new Matrix room with an optional topic.

func (*Client) CreateRoomWithAlias 

func (c *Client) CreateRoomWithAlias(name, topic, aliasName string) (*Room, error)

CreateRoomWithAlias creates a room with a canonical alias.

func (*Client) EventContext 

func (c *Client) EventContext(roomID, eventID string) (string, error)

EventContext returns the pagination token after a given event.

func (*Client) GetDirectRooms 

func (c *Client) GetDirectRooms(userID string) (map[string][]string, error)

GetDirectRooms retrieves the m.direct account data for the user.

func (*Client) GetPresence 

func (c *Client) GetPresence(userID string) (*PresenceResponse, error)

GetPresence retrieves a user's presence status.

func (*Client) GetProfile 

func (c *Client) GetProfile(userID string) error

GetProfile retrieves a user's profile. Returns an error if the user does not exist.

func (*Client) GetRoomInfo 

func (c *Client) GetRoomInfo(roomID string) (*RoomInfo, error)

GetRoomInfo retrieves the name and topic for a room.

func (*Client) Invite 

func (c *Client) Invite(roomID, userID string) error

Invite invites a user to a room.

func (*Client) Join 

func (c *Client) Join(roomIDOrAlias string) (string, error)

Join joins a room by ID or alias.

func (*Client) JoinedRooms 

func (c *Client) JoinedRooms() (*JoinedRooms, error)

JoinedRooms returns the list of rooms the user has joined.

func (*Client) Leave 

func (c *Client) Leave(roomID string) error

Leave leaves a room.

func (*Client) Login 

func (c *Client) Login(username, password string) (*Registration, error)

Login authenticates and returns an access token.

func (*Client) Members 

func (c *Client) Members(roomID string) ([]Member, error)

Members returns the joined members of a room with display names.

func (*Client) Messages 

func (c *Client) Messages(roomID string, limit int) (*Messages, error)

Messages retrieves recent messages from a room.

func (*Client) MessagesFrom 

func (c *Client) MessagesFrom(roomID, from string, limit int, dir string) (*Messages, error)

MessagesFrom retrieves messages starting from a pagination token.

func (*Client) PublicRooms 

func (c *Client) PublicRooms() (*PublicRoomsResponse, error)

PublicRooms returns public rooms on the server.

func (*Client) Register 

func (c *Client) Register(username, password, token string) (*Registration, error)

Register creates a new Matrix user account.

func (*Client) ResolveAlias 

func (c *Client) ResolveAlias(alias string) (*AliasResponse, error)

ResolveAlias resolves a room alias to a room ID.

func (*Client) Send 

func (c *Client) Send(roomID, message string) (string, error)

Send sends a text message to a room and returns the event ID.

func (*Client) SetDirectRooms 

func (c *Client) SetDirectRooms(userID string, rooms map[string][]string) error

SetDirectRooms updates the m.direct account data for the user.

func (*Client) SetRoomAlias 

func (c *Client) SetRoomAlias(alias, roomID string) error

SetRoomAlias registers an alias for a room.

func (*Client) Sync 

func (c *Client) Sync(ctx context.Context, since string, timeout int, roomID string) (*SyncResponse, error)

Sync performs a Matrix sync request. timeout is in seconds.

func (*Client) WhoAmI 

func (c *Client) WhoAmI() (*WhoAmIResponse, error)

WhoAmI returns the user ID for the current access token.

type Config 

type Config struct {
	Homeserver string `yaml:"homeserver"`
}

Config holds mtx configuration.

type DMRoomCreator 

type DMRoomCreator func(invite string) (*Room, error)

DMRoomCreator creates a direct-message room with an invited user.

type EventContextGetter 

type EventContextGetter func(roomID, eventID string) (string, error)

EventContextGetter returns a pagination token after a given event.

type Inviter 

type Inviter func(roomID, userID string) error

Inviter invites a user to a Matrix room.

type JoinedRooms 

type JoinedRooms struct {
	Rooms []string `json:"joined_rooms"`
}

JoinedRooms is returned when listing joined rooms.

type Member 

type Member struct {
	UserID      string `json:"user_id"`
	DisplayName string `json:"display_name"`
}

Member represents a room member with their display name.

type MemberLister 

type MemberLister func(roomID string) ([]Member, error)

MemberLister lists the members of a room.

type Message 

type Message struct {
	Sender  string                 `json:"sender"`
	Type    string                 `json:"type"`
	Content map[string]interface{} `json:"content"`
	EventID string                 `json:"event_id"`
}

Message represents a single Matrix timeline event.

type MessageFromReader 

type MessageFromReader func(roomID, from string, limit int, dir string) (*Messages, error)

MessageFromReader reads messages starting from a pagination token.

type MessageReader 

type MessageReader func(roomID string, limit int) (*Messages, error)

MessageReader reads messages from a Matrix room.

type MessageSender 

type MessageSender func(roomID, message string) (string, error)

MessageSender sends a message to a Matrix room.

type Messages 

type Messages struct {
	End   string    `json:"end"`
	Chunk []Message `json:"chunk"`
}

Messages is the response from the room messages endpoint.

type PresenceResponse 

type PresenceResponse struct {
	Presence        string `json:"presence"`
	LastActiveAgo   int    `json:"last_active_ago"`
	CurrentlyActive bool   `json:"currently_active"`
}

PresenceResponse is returned by the presence endpoint.

type PublicRoom 

type PublicRoom struct {
	RoomID         string `json:"room_id"`
	Name           string `json:"name"`
	Topic          string `json:"topic"`
	CanonicalAlias string `json:"canonical_alias"`
	NumJoined      int    `json:"num_joined_members"`
}

PublicRoom represents a room in the public room listing.

type PublicRoomLister 

type PublicRoomLister func() (*PublicRoomsResponse, error)

PublicRoomLister lists public rooms on the server.

type PublicRoomsResponse 

type PublicRoomsResponse struct {
	Chunk []PublicRoom `json:"chunk"`
}

PublicRoomsResponse is the response from the public rooms endpoint.

type Registerer 

type Registerer func(username, password, token string) (*Registration, error)

Registerer registers a Matrix user account.

type Registration 

type Registration struct {
	UserID      string `json:"user_id"`
	AccessToken string `json:"access_token"`
	DeviceID    string `json:"device_id"`
}

Registration is returned by register and login endpoints.

type Room 

type Room struct {
	RoomID string `json:"room_id"`
}

Room is returned when creating a room.

type RoomCreator 

type RoomCreator func(name, topic string) (*Room, error)

RoomCreator creates a Matrix room.

type RoomInfo 

type RoomInfo struct {
	Name  string `json:"name"`
	Topic string `json:"topic"`
}

RoomInfo holds a room's name and topic.

type RoomInfoGetter 

type RoomInfoGetter func(roomID string) (*RoomInfo, error)

RoomInfoGetter retrieves room name and topic.

type RoomJoiner 

type RoomJoiner func(roomIDOrAlias string) (string, error)

RoomJoiner joins a room by ID or alias.

type RoomLeaver 

type RoomLeaver func(roomID string) error

RoomLeaver leaves a room.

type RoomLister 

type RoomLister func() (*JoinedRooms, error)

RoomLister lists joined Matrix rooms.

type SyncInviteState 

type SyncInviteState struct {
	Events []Message `json:"events"`
}

SyncInviteState contains stripped state events for an invited room.

type SyncInvitedRoom 

type SyncInvitedRoom struct {
	InviteState SyncInviteState `json:"invite_state"`
}

SyncInvitedRoom contains invite state from a sync response.

type SyncJoinedRoom 

type SyncJoinedRoom struct {
	Timeline SyncTimeline `json:"timeline"`
}

SyncJoinedRoom contains timeline data for a joined room.

type SyncResponse 

type SyncResponse struct {
	Rooms     SyncRooms `json:"rooms"`
	NextBatch string    `json:"next_batch"`
}

SyncResponse is a simplified Matrix sync response.

type SyncRooms 

type SyncRooms struct {
	Join   map[string]SyncJoinedRoom  `json:"join"`
	Invite map[string]SyncInvitedRoom `json:"invite"`
}

SyncRooms contains room data from a sync response.

type SyncTimeline 

type SyncTimeline struct {
	Events []Message `json:"events"`
}

SyncTimeline contains timeline events from a sync.

type WhoAmIGetter 

type WhoAmIGetter func() (*WhoAmIResponse, error)

WhoAmIGetter retrieves the current user's identity.

type WhoAmIResponse 

type WhoAmIResponse struct {
	UserID string `json:"user_id"`
}

WhoAmIResponse is returned by the whoami endpoint.

Source Files

View all Source files

Directories

Path Synopsis
cmd
mtx command
Package main provides the mtx CLI entrypoint.
 Package main provides the mtx CLI entrypoint.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.