README

View Source

HexDocs

Sambex

Sambex is a library for interacting with SMB (Server Message Block) shares in Elixir.

Questions

Because a little role-play solves many problems.

Q: Is it any good?
A: No. It's not. Not yet.

Q: Should you install it?
A: No. It's not ready yet.

Q: I used this in production and everything went wrong.
A: Thanks for doing QA - please report any issues on GitHub.

Q: Should I install it anyway?
A: Sure. I mean, what other options do you have?

Features

✅ Complete SMB Operations

  • Connect to SMB shares with authentication
  • List directory contents
  • Read files from SMB shares
  • Write/create files on SMB shares
  • Delete files from SMB shares (now working!)
  • Move/rename files on SMB shares (new!)
  • Get file metadata/statistics (new!)
  • Upload local files to SMB shares
  • Download files from SMB shares

✅ Robust Implementation

  • Written in Zig with Elixir NIF interface
  • Proper error handling and context management
  • Support for binary and Unicode content
  • Large file operations
  • Multiple share support

✅ Comprehensive Testing

  • Unit tests for basic functionality
  • Integration tests against real SMB server
  • 33 tests covering all operations
  • Docker-based test environment

Installation

Sambex can be installed by adding sambex to your list of dependencies in mix.exs:

def deps do
  [
    {:sambex, "~> 0.1.1"}
  ]
end

Usage

You must ensure to initialize the library before using it.

iex> Sambex.init()
:ok

Then you can use the library to interact with SMB shares.

iex> Sambex.list_dir("smb://localhost:445/private", "example2", "badpass")
{:ok, ["thing", "thing2"]}

iex> Sambex.read_file("smb://localhost:445/private/thing", "example2", "badpass")
{:ok, "thing\n"}

iex> Sambex.write_file("smb://localhost:445/private/thing2", "some content", "example2", "badpass")
{:ok, 12}

iex> Sambex.move_file("smb://localhost:445/private/old_name.txt", "smb://localhost:445/private/new_name.txt", "example2", "badpass")
:ok

iex> Sambex.get_file_stats("smb://localhost:445/private/thing", "example2", "badpass")
{:ok, %{size: 5, type: :file, mode: 420, access_time: 1754953764, modification_time: 1754953764, change_time: 1754953764, uid: 501, gid: 20, links: 1}}

Testing

Sambex includes a comprehensive test suite with both unit and integration tests.

Quick Start

# Run all tests
mix test

# Run only unit tests (fast, no dependencies)
mix test --exclude integration

# Run only integration tests (requires SMB server)
mix test --only integration

Test Runner

Use the interactive test runner for a better experience:

./test_runner.exs --help
./test_runner.exs --unit
./test_runner.exs --integration
./test_runner.exs --all

Test Environment

The integration tests require a Docker-based SMB server:

# Start test SMB server
docker-compose up -d

# Run integration tests
mix test --only integration

# Stop test server
docker-compose down

Test Coverage

  • 33 total tests covering all functionality
  • Unit tests: Module structure, function exports, validation
  • Integration tests: Complete file operations against real SMB server
  • Error handling: Wrong credentials, non-existent files, network issues
  • Edge cases: Empty files, large files, Unicode content, binary data

For detailed testing information, see test/README.md.

Roadmap

✅ Completed Features

  • [x] Connect to SMB shares
  • [x] List directory contents
  • [x] Read files
  • [x] Write/create files
  • [x] Delete files
  • [x] Move/rename files
  • [x] Get file metadata/statistics
  • [x] Upload local files
  • [x] Download files
  • [x] Authentication support
  • [x] Multiple share support
  • [x] Comprehensive testing

🚧 Future Features

  • [ ] Create directory
  • [ ] Rename directory
  • [ ] Delete directory
  • [ ] Set file permissions
  • [ ] Symbolic link support

CI/CD

Sambex includes comprehensive GitHub Actions workflows for continuous integration and deployment.

Automated Testing

Every push and pull request triggers:

  • Unit Tests: Fast tests without external dependencies
  • Integration Tests: Full SMB operations against real server
  • Code Quality: Credo static analysis and formatting checks
  • Coverage: Test coverage reporting
  • Multi-version: Tests across Elixir 1.17-1.18 and OTP 26-27

GitHub Actions Workflows

Main CI Workflow (.github/workflows/ci.yml)

# Triggered on push/PR to main branches
- Unit tests (all Elixir/OTP combinations)
- Integration tests with Docker Samba server
- Code formatting and quality checks
- Coverage reporting
- Release build verification

Comprehensive Test Workflow (.github/workflows/test.yml)

# More detailed testing pipeline
- Separate unit and integration test jobs
- Detailed SMB server configuration
- Coverage analysis with Coveralls
- Code quality with Credo and Dialyzer
- Release verification

Running Locally

Test the same pipeline locally:

# Run the same checks as CI
mix format --check-formatted
mix compile --warnings-as-errors
mix test
mix credo --strict
mix docs

# With coverage
mix test --cover

CI Environment Setup

The CI automatically:

  1. Installs Elixir/OTP and system dependencies
  2. Starts Docker Samba server with test configuration
  3. Configures users and shares for testing
  4. Runs comprehensive test suite
  5. Reports results and coverage

Contributing

All contributions must pass CI checks:

  • [ ] All tests pass
  • [ ] Code formatting is correct
  • [ ] No new Credo warnings
  • [ ] Documentation is updated
  • [ ] Coverage is maintained

See .github/pull_request_template.md for details.