First version

Author: valentineus

README.md

@@ -0,0 +1,47 @@
+# MT4 Client Library
+
+A lightweight Go client library for interacting with a MetaTrader 4 (MT4) trading server over TCP.
+
+## Example Usage
+
+```go
+import "go.popov.link/metatrader4/mt4"
+
+client := mt4.NewClient("127.0.0.1", 443,
+    mt4.WithDialTimeout(3*time.Second),
+    mt4.WithAutoClose(true),
+)
+ctx := context.Background()
+params := map[string]string{
+    "login":    "55555",
+    "password": "_some_password_",
+}
+res, err := client.Execute(ctx, "WWAPUSER", params)
+```
+
+The `Execute` method sends a raw MT4 command. Parameters are encoded using base64 and Windows-1251.
+Use `WithAutoClose(false)` if you want to reuse the connection manually via `client.Close()`.
+
+## Options
+
+- `WithDialTimeout(d time.Duration)`: Sets the timeout for establishing a TCP connection. Default: 5s.
+- `WithReadTimeout(d time.Duration)`: Sets the maximum time to wait for a server response. Default: 5s.
+- `WithWriteTimeout(d time.Duration)`: Sets the maximum time to complete sending a request. Default: 5s.
+- `WithAutoClose(enabled bool)`: If `true`, closes the connection after each `Execute` (default). Use `false` to reuse the session manually via `client.Close()`.
+
+## Requirements
+
+- Go 1.24 or later
+- MetaTrader 4 server with TCP access
+
+## Maintainer & Project Info
+
+- Vanity import path: `go.popov.link/metatrader4`
+- Source mirror (read-only): [code.popov.link](https://code.popov.link/valentineus/go-metatrader4)
+- Issues and contributions: [GitHub](https://github.com/valentineus/go-metatrader4/issues)
+
+Maintained by [Valentin Popov](mailto:[email protected]).
+
+## License
+
+This project is licensed under the [MIT License](LICENSE.txt).

examples/info/README.md

@@ -0,0 +1,53 @@
+# Example: INFO Command
+
+This example demonstrates how to use the [`go-metatrader4`](https://github.com/valentineus/go-metatrader4) library to send the `INFO` command to a MetaTrader 4 (MT4) server and retrieve server information.
+
+The `INFO` command requests basic server details such as build version and company name.
+
+## Usage
+
+To run this example:
+
+```bash
+go run main.go
+```
+
+Make sure you are connected to an MT4 server that accepts TCP connections on the configured host and port.
+
+## Code Overview
+
+```go
+client := mt4.NewClient("127.0.0.1", 443,
+    mt4.WithDialTimeout(3*time.Second),
+    mt4.WithReadTimeout(5*time.Second),
+    mt4.WithWriteTimeout(5*time.Second),
+)
+ctx := context.Background()
+resp, err := client.Execute(ctx, "INFO", nil)
+
+```
+
+This code creates an MT4 client, sends the INFO command without parameters, and prints the response to stdout.
+
+## Expected Response Format
+
+The response typically looks like this:
+
+```text
+MetaTrader 4 Server 4.00 build 1380
+Some Broker Company Name
+```
+
+Where:
+
+- `build 1380` — current server build number
+- `Some Broker Company Name` — name of the White Label owner of the server
+
+## Requirements
+
+- Go 1.24 or later
+- Access to a running MetaTrader 4 server
+
+## License
+
+This example is provided under the MIT License. See the [main project license](../../LICENSE.txt) for details.

examples/info/main.go

@@ -0,0 +1,25 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"time"
+
+	"go.popov.link/metatrader4/mt4"
+)
+
+func main() {
+	client := mt4.NewClient("127.0.0.1", 443,
+		mt4.WithDialTimeout(3*time.Second),
+		mt4.WithReadTimeout(5*time.Second),
+		mt4.WithWriteTimeout(5*time.Second),
+	)
+	ctx := context.Background()
+	// INFO does not require parameters
+	resp, err := client.Execute(ctx, "INFO", nil)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println(resp)
+}

go.mod

@@ -1,3 +1,5 @@
-module github.com/valentineus/go-metatrader4
+module go.popov.link/metatrader4
 
 go 1.24.2
+
+require golang.org/x/text v0.25.0

go.sum

@@ -0,0 +1,2 @@
+golang.org/x/text v0.25.0 h1:qVyWApTSYLk/drJRO5mDlNYskwQznZmkpV2c8q9zls4=
+golang.org/x/text v0.25.0/go.mod h1:WEdwpYrmk1qmdHvhkSTNPm3app7v4rsT8F2UD6+VHIA=

internal/.gitkeep

@@ -0,0 +1,50 @@
+package conn
+
+import (
+	"context"
+	"io"
+	"net"
+	"time"
+)
+
+type Conn struct {
+	netConn net.Conn
+}
+
+// FromNetConn wraps an existing net.Conn. Useful for tests.
+func FromNetConn(n net.Conn) *Conn { return &Conn{netConn: n} }
+
+func Dial(ctx context.Context, addr string, timeout time.Duration) (*Conn, error) {
+	d := net.Dialer{Timeout: timeout}
+	c, err := d.DialContext(ctx, "tcp", addr)
+	if err != nil {
+		return nil, err
+	}
+	return &Conn{netConn: c}, nil
+}
+
+func (c *Conn) Close() error {
+	if c.netConn == nil {
+		return nil
+	}
+	return c.netConn.Close()
+}
+
+func (c *Conn) Send(ctx context.Context, data []byte, timeout time.Duration) error {
+	if dl, ok := ctx.Deadline(); ok {
+		c.netConn.SetWriteDeadline(dl)
+	} else {
+		c.netConn.SetWriteDeadline(time.Now().Add(timeout))
+	}
+	_, err := c.netConn.Write(data)
+	return err
+}
+
+func (c *Conn) Receive(ctx context.Context, timeout time.Duration) ([]byte, error) {
+	if dl, ok := ctx.Deadline(); ok {
+		c.netConn.SetReadDeadline(dl)
+	} else {
+		c.netConn.SetReadDeadline(time.Now().Add(timeout))
+	}
+	return io.ReadAll(c.netConn)
+}

internal/conn/conn.go

@@ -0,0 +1,65 @@
+package proto
+
+import (
+	"encoding/base64"
+	"fmt"
+	"sort"
+	"strings"
+	"unicode"
+
+	"golang.org/x/text/encoding/charmap"
+)
+
+// EncodeParams converts params map into a sorted base64-encoded string using Windows-1251 encoding.
+func EncodeParams(params map[string]string) (string, error) {
+	keys := make([]string, 0, len(params))
+	for k := range params {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+
+	var sb strings.Builder
+	for i, k := range keys {
+		if i > 0 {
+			sb.WriteByte('|')
+		}
+		sb.WriteString(k)
+		sb.WriteByte('=')
+		sb.WriteString(params[k])
+	}
+	sb.WriteByte('|')
+
+	enc := charmap.Windows1251.NewEncoder()
+	encoded, err := enc.String(sb.String())
+	if err != nil {
+		return "", fmt.Errorf("encode params: %w", err)
+	}
+	return base64.StdEncoding.EncodeToString([]byte(encoded)), nil
+}
+
+// DecodeResponse decodes base64-encoded Windows-1251 text to UTF-8 and removes control characters.
+func DecodeResponse(data string) (string, error) {
+	raw, err := base64.StdEncoding.DecodeString(strings.TrimSpace(data))
+	if err != nil {
+		return "", fmt.Errorf("base64 decode: %w", err)
+	}
+	decoded, err := charmap.Windows1251.NewDecoder().Bytes(raw)
+	if err != nil {
+		return "", fmt.Errorf("decode charset: %w", err)
+	}
+	cleaned := strings.Map(func(r rune) rune {
+		if unicode.IsPrint(r) || r == '\n' || r == '\r' || r == '\t' {
+			return r
+		}
+		return -1
+	}, string(decoded))
+	return cleaned, nil
+}
+
+// BuildRequest returns byte slice representing the command and parameters.
+func BuildRequest(command, encodedParams string, quit bool) []byte {
+	if quit {
+		return []byte(fmt.Sprintf("%s %s\nQUIT\n", command, encodedParams))
+	}
+	return []byte(fmt.Sprintf("%s %s\n", command, encodedParams))
+}

internal/proto/proto.go

@@ -0,0 +1,39 @@
+package proto
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestEncodeParamsOrder(t *testing.T) {
+	params := map[string]string{"B": "2", "A": "1"}
+	encoded1, err := EncodeParams(params)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	// encode again with different map order
+	encoded2, err := EncodeParams(map[string]string{"A": "1", "B": "2"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if encoded1 != encoded2 {
+		t.Fatalf("expected deterministic encode, got %s vs %s", encoded1, encoded2)
+	}
+}
+
+func TestDecodeResponse(t *testing.T) {
+	// "привет" in Cyrillic
+	original := "привет"
+	params := map[string]string{"MSG": original}
+	enc, err := EncodeParams(params)
+	if err != nil {
+		t.Fatalf("encode params: %v", err)
+	}
+	dec, err := DecodeResponse(enc)
+	if err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if !strings.Contains(dec, original) {
+		t.Fatalf("expected to contain %q, got %q", original, dec)
+	}
+}