tg_bot_golang

Telegram bot that saves links from users and periodically sends one random saved link back after every SEND_EVERY_N saved links.

How It Works

• User sends a full http:// or https:// URL.
• The bot validates and saves the link for that Telegram user.
• Duplicate links are ignored and reported to the user.
• The bot increments the user's saved-link counter.
• If the counter is divisible by SEND_EVERY_N, the bot sends a random saved link.
• /rnd sends a random saved link manually.
• /start and /help show help text.

Architecture

The project keeps the existing package layout:

• app/ - application bootstrap, dependency wiring, logger, graceful shutdown.
• clients/telegram - Telegram HTTP client.
• consumer/poller - event polling orchestration.
• events/telegram - Telegram event parsing and command routing.
• service/ - business logic for links, counters, URL validation, random-send decision.
• storage/ - storage interface plus sqlite and files implementations.
• config/ - environment configuration.
• lib/e - small error wrapping helpers.

More detail is in ARCHITECTURE.md.

Configuration

Use .env.example as a template, then export variables in your shell or process manager:

cp .env.example .env
set -a
source .env
set +a

The application reads os.Getenv only. It does not auto-load .env.

Required variables:

• BOT_TOKEN - Telegram bot token from BotFather.
• DATABASE_PATH - sqlite database file path, for example data/sqlite/storage.db.
• SEND_EVERY_N - send a random saved link after every N saved links.

Optional variables:

• LOG_LEVEL - debug, info, warn, or error. Defaults to info.
• ENV - local, dev, staging, or production. Defaults to local.

DATABASE_URL is accepted as a fallback for DATABASE_PATH. TELEGRAM_HOST is optional and defaults to api.telegram.org. It may also be set to a full base URL for testing through a local proxy or mock server. Invalid values fail startup with a regular configuration error.

Local Run

Export env variables, then run:

go run .

Or:

make run

The app creates the sqlite directory and schema on startup.

Tests

go test ./...
go test -race ./...

Convenience target:

make test

Quality Checks

test -z "$(gofmt -l .)"
go vet ./...

Or:

make lint

Storage

Production storage is sqlite. It creates:

• links with user_id, link, created_at, and a unique (user_id, link) constraint.
• message_counters with user_id, count, and updated_at.
• bot_state for internal runtime state such as the persisted Telegram update offset.

The files storage remains available as a lightweight implementation of the storage interface, but sqlite is the recommended production backend.

Structure

• main.go stays thin and delegates bootstrap into app.Run().
• Import paths are lowercase and package names avoid underscores and hyphens.
• Runtime dependencies are wired once in app/, while transport and business logic remain isolated.
• Telegram update acknowledgements are persisted in sqlite after successful processing, which avoids replaying the full unconfirmed batch after restart.

CI

GitHub Actions workflow is in .github/workflows/ci.yml and runs:

• go mod download
• gofmt check
• go vet ./...
• go test ./...
• go test -race ./...

Documentation

• Static docs site source is in docs/.
• GitHub Pages deployment workflow is in .github/workflows/pages.yml.
• After enabling Pages with the GitHub Actions source in repository settings, pushes to main publish the docs site automatically.

Troubleshooting

• BOT_TOKEN is required: export BOT_TOKEN in the environment before running.
• DATABASE_PATH or DATABASE_URL is required: set a sqlite path.
• invalid telegram api base url: fix TELEGRAM_HOST so it is a valid host or full base URL.
• duplicate link: the bot ignores repeated links for the same user.
• No random link is sent: verify SEND_EVERY_N and that the user has saved links.
• sqlite build errors: github.com/mattn/go-sqlite3 uses CGO, so install a C compiler in the runtime/build image.