{"id":30746767,"url":"https://github.com/gabrielalmir/hush","last_synced_at":"2025-10-04T07:13:18.299Z","repository":{"id":282620686,"uuid":"948990530","full_name":"gabrielalmir/hush","owner":"gabrielalmir","description":"A lightweight, Redis-compatible in-memory data store implemented in Python with async/await support.","archived":false,"fork":false,"pushed_at":"2025-08-15T10:44:12.000Z","size":13,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-04T04:43:26.782Z","etag":null,"topics":["asyncio","caching","lru-cache","pytest","python","queue","unit-testing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gabrielalmir.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-15T12:32:03.000Z","updated_at":"2025-08-15T10:44:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"d82f681b-54c5-4c01-994c-84a9434b3120","html_url":"https://github.com/gabrielalmir/hush","commit_stats":null,"previous_names":["gabrielalmir/vibe-hush","gabrielalmir/hush"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gabrielalmir/hush","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielalmir%2Fhush","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielalmir%2Fhush/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielalmir%2Fhush/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielalmir%2Fhush/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gabrielalmir","download_url":"https://codeload.github.com/gabrielalmir/hush/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielalmir%2Fhush/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278279027,"owners_count":25960624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","caching","lru-cache","pytest","python","queue","unit-testing"],"created_at":"2025-09-04T04:28:10.468Z","updated_at":"2025-10-04T07:13:18.290Z","avatar_url":"https://github.com/gabrielalmir.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hush\n\nA lightweight, Redis-compatible in-memory data store implemented in Python with async/await support.\n\n## Features\n\n- **Redis Protocol Compatible**: Implements the RESP (Redis Serialization Protocol) for seamless integration with Redis clients\n- **LRU Cache**: Built-in Least Recently Used cache with configurable capacity (default: 1000 items)\n- **TTL Support**: Time-to-live functionality for automatic key expiration\n- **Queue Operations**: Support for list operations like LPUSH and BLPOP\n- **Async/Await**: Fully asynchronous implementation using Python's asyncio\n- **Thread-Safe**: All operations are protected with async locks\n\n## Supported Commands\n\n### Cache Operations\n- `SET key value [EX seconds]` - Set a key-value pair with optional TTL\n- `GET key` - Retrieve the value for a key\n- `DEL key` - Delete a key\n\n### Queue Operations\n- `LPUSH key value [value ...]` - Push values to the left of a list\n- `BLPOP key [key ...] timeout` - Blocking pop from the left of lists\n\n## Installation\n\n### Prerequisites\n- Python 3.12 or higher\n- uv (recommended) or pip\n\n### Using uv (recommended)\n```bash\ngit clone https://github.com/gabrielalmir/hush\ncd hush\nuv sync\n```\n\n### Using pip\n```bash\ngit clone https://github.com/gabrielalmir/hush\ncd hush\npip install -e .\n```\n\n## Usage\n\n### Starting the Server\n\n```bash\n# Using uv\nuv run python main.py\n\n# Using python directly\npython main.py\n\n# Custom port and host\npython main.py --port 6380 --host 127.0.0.1\n```\n\nThe server will start on `0.0.0.0:6379` by default (same as Redis).\n\n### Connecting with Redis CLI\n\nSince Hush implements the Redis protocol, you can use any Redis client:\n\n```bash\n# Using redis-cli\nredis-cli -h localhost -p 6379\n\n# Example commands\n127.0.0.1:6379\u003e SET mykey \"Hello World\"\nOK\n127.0.0.1:6379\u003e GET mykey\n\"Hello World\"\n127.0.0.1:6379\u003e SET tempkey \"expires soon\" EX 10\nOK\n127.0.0.1:6379\u003e LPUSH mylist \"item1\" \"item2\"\n(integer) 2\n127.0.0.1:6379\u003e BLPOP mylist 5\n1) \"mylist\"\n2) \"item2\"\n```\n\n### Using Python Redis Client\n\n```python\nimport redis\n\n# Connect to Hush server\nr = redis.Redis(host='localhost', port=6379, decode_responses=True)\n\n# Cache operations\nr.set('key1', 'value1')\nprint(r.get('key1'))  # Output: value1\n\n# TTL operations\nr.setex('temp_key', 10, 'expires in 10 seconds')\n\n# Queue operations\nr.lpush('myqueue', 'task1', 'task2')\nresult = r.blpop('myqueue', timeout=5)\nprint(result)  # Output: ('myqueue', 'task2')\n```\n\n## Architecture\n\n### Components\n\n- **HushServer**: Main server class that handles client connections and command routing\n- **Cache**: LRU cache implementation with TTL support\n- **Queue**: Queue operations using Python's deque for efficient list operations\n- **RESP Parser**: Redis protocol parser and serializer\n\n### Cache Implementation\n\n- Uses a combination of hashmap and doubly-linked list for O(1) operations\n- Automatic eviction of least recently used items when capacity is exceeded\n- TTL-based expiration with automatic cleanup on access\n\n### Concurrency\n\n- All operations are async and use asyncio locks for thread safety\n- Non-blocking I/O for handling multiple concurrent clients\n- Efficient memory usage with Python's async/await patterns\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run with verbose output\nuv run pytest -v\n\n# Run specific test file\nuv run pytest tests/test_cache.py\n```\n\n### Project Structure\n\n```\nhush/\n├── src/\n│   ├── __init__.py\n│   ├── cache.py      # LRU cache implementation\n│   ├── queue.py      # Queue operations\n│   ├── resp.py       # Redis protocol parser\n│   └── server.py     # Main server implementation\n├── tests/\n│   ├── test_cache.py\n│   ├── test_queue.py\n│   └── test_resp.py\n├── main.py           # Server entry point\n└── pyproject.toml    # Project configuration\n```\n\n## Performance Characteristics\n\n- **Cache Operations**: O(1) average time complexity for GET, SET, DEL\n- **Queue Operations**: O(1) for LPUSH, O(1) for BLPOP when items available\n- **Memory Usage**: Efficient memory usage with automatic LRU eviction\n- **Concurrency**: Supports multiple concurrent clients with async I/O\n\n## Limitations\n\n- In-memory only (data is not persisted to disk)\n- Single-node deployment (no clustering support)\n- Limited Redis command set (focused on core cache and queue operations)\n- No authentication or access control\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Run the test suite\n6. Submit a pull request\n\n## License\n\nThis project is open source. Please check the license file for details.\n\n## Roadmap\n\n- [ ] Additional Redis commands (HSET, HGET, SADD, etc.)\n- [ ] Persistence options\n- [ ] Configuration file support\n- [ ] Metrics and monitoring\n- [ ] Clustering support\n- [ ] Authentication and authorization\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabrielalmir%2Fhush","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgabrielalmir%2Fhush","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabrielalmir%2Fhush/lists"}