No description
Find a file
Giuseppe Pagano 87e0321697 init
2025-12-05 12:55:33 +01:00
example init 2025-12-05 12:55:33 +01:00
.gitignore init 2025-12-05 12:55:33 +01:00
go.mod init 2025-12-05 12:55:33 +01:00
go.sum init 2025-12-05 12:55:33 +01:00
main.go init 2025-12-05 12:55:33 +01:00
README.md init 2025-12-05 12:55:33 +01:00
types.go init 2025-12-05 12:55:33 +01:00
websocket.go init 2025-12-05 12:55:33 +01:00

Mattermost WebSocket Client

A Go client for the Mattermost WebSocket interface, designed to receive and handle real-time events.

Project Status

⚠️ Early Development Phase ⚠️

This project is in its early stages of development. APIs may change and not all features are implemented yet.

Features

  • Secure WebSocket connection to Mattermost
  • Automatic event handling
  • Read-only support: Currently supports only receiving data from Mattermost
  • zerolog logging support
  • Context-aware for clean connection management
  • Complete example included

Installation

This library is designed to be forge-independent and can be used from any Git repository. Instead of publishing to a specific forge, use Go's replace directive to include it in your project.

Method 1: Direct replace in go.mod

Add this to your go.mod file:

module your-project

go 1.21

require (
    mattermost_ws_client v0.0.0
)

replace mattermost_ws_client => /path/to/local/mattermost-ws-client

Method 2: Using go mod edit

go mod edit -replace mattermost_ws_client=/path/to/local/mattermost-ws-client
go mod tidy

Method 3: Remote Git repository

If you have the code in a remote Git repository:

go mod edit -replace mattermost_ws_client=github.com/yourusername/mattermost-ws-client@main
go mod tidy

This approach keeps the library independent from any specific code hosting platform.

Personal Access Token Setup

To use this client, you need a Mattermost personal access token:

1. Access Mattermost

Log in to your Mattermost instance as an administrator or user with appropriate privileges.

2. Create Token

  1. Go to Account SettingsSecurityPersonal Access Tokens
  2. Click Create Token
  3. Provide a description (e.g., "WebSocket Client")
  4. Copy the generated token (it will only be shown once!)

Basic Usage

package main

import (
    "context"
    mc "mattermost_ws_client"
)

func main() {
    client := mc.NewMattermostWSClient("wss://mattermost.example.com/api/v4/websocket", "your-token")
    
    ctx := context.Background()
    envelopeChan, err := client.Listen(ctx)
    if err != nil {
        // handle error
        return
    }
    
    for envelope := range envelopeChan {
        // process events
        println("Event received:", envelope.Event)
    }
}

Logging

The library uses zerolog for logging. By default, logs are disabled.

Enable Logging

import (
    "os"
    "github.com/rs/zerolog"
    "github.com/rs/zerolog/log"
)

// Enable console logging
log.Logger = log.Output(zerolog.ConsoleWriter{
    Out: os.Stdout, 
    TimeFormat: time.RFC3339,
})

Complete Example

A working example is available in the example/ folder. To run it:

cd example
export WS_URL="wss://your-mattermost-instance.com/api/v4/websocket"
export MM_TOKEN="your-personal-access-token"
go run main.go

Supported Event Types

Currently the client handles generic events. Main event types include:

  • posted: New message posted

Dependencies

Contributing

The project is open to contributions! Feel free to:

  • Report bugs
  • Propose new features
  • Submit pull requests
  • Improve documentation

Note: Make sure your personal access token has the appropriate permissions to access the channels and events you want to monitor.