MrKalzu/kvs-sh
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Initial commit. The shell now combiles and runs.

Browse Source
This commit is contained in:
Kalzu Rekku
2025-10-05 20:03:35 +03:00
commit 3ae9395f9d
4 changed files with 843 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

257
README.md Normal file
View File

@@ -0,0 +1,257 @@
# KVS Shell
An interactive command-line client for the KVS (Key-Value Store) distributed database system.
## Overview
KVS Shell is a terminal-based client that provides an intuitive interface for interacting with KVS servers. It offers features similar to `mongosh`, `psql`, or `redis-cli`, allowing you to manage key-value data, users, groups, and cluster members through a simple command interface.
## Features
- **Interactive Shell**: Full-featured REPL with command history and auto-completion
- **Profile Management**: Switch between multiple user accounts and servers
- **Authentication**: JWT token-based authentication with secure credential storage
- **Key-Value Operations**: Store, retrieve, and delete JSON data
- **Cluster Management**: Monitor cluster members and health status
- **User Management**: View and manage user accounts (with appropriate permissions)
- **Colored Output**: Syntax-highlighted responses for better readability
## Installation
### Prerequisites
- Go 1.21 or higher
- Access to a running KVS server
### Build from Source
```bash
git clone
cd kvs-shell
go mod tidy
go build -o kvs-shell
```
### Install
```bash
# Install to your Go bin directory
go install
# Or copy the binary to your PATH
sudo cp kvs-shell /usr/local/bin/
```
## Quick Start
1. Start the shell:
```bash
./kvs-shell
```
2. Connect to your KVS server:
```
kvs> connect http://localhost:8090
```
3. Authenticate (if required):
```
kvs> auth eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
4. Store and retrieve data:
```
kvs> put users/alice {"name": "Alice", "email": "alice@example.com"}
kvs> get users/alice
```
## Commands Reference
### Connection & Authentication
```bash
connect <url> # Connect to KVS server
auth <token> # Set authentication token
```
### Profile Management
```bash
profile # List all saved profiles
profile add <name> <token> <user-uuid> [url] # Add a new profile
profile use <name> # Switch to a profile
profile remove <name> # Delete a profile
```
**Example:**
```
kvs> profile add admin eyJhbG... user-uuid-123 http://localhost:8090
kvs> profile add dev eyJhbG... user-uuid-456 http://localhost:8091
kvs> profile use dev
```
### Key-Value Operations
```bash
get <key> # Retrieve value for key
put <key> <json> # Store JSON value at key
delete <key> # Delete key
```
**Examples:**
```
kvs> put config/app {"version": "1.0", "debug": true}
kvs> get config/app
kvs> delete config/old
```
### Cluster Management
```bash
members # List cluster members
health # Check service health
```
### User Management
```bash
user get <uuid> # Get user details
user create <nickname> # Create new user (admin only)
```
### System Commands
```bash
help # Show help
clear # Clear screen
exit, quit # Exit shell
```
## Response Format
### Stored Values
When retrieving data with `get`, you'll see:
```
UUID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Timestamp: 2025-10-05T12:34:56Z
Data:
{
"name": "Alice",
"email": "alice@example.com"
}
```
### Cluster Members
The `members` command shows:
```
Cluster Members:
• node-1 (192.168.1.10:8090) - Last seen: 2025-10-05T12:34:56Z
• node-2 (192.168.1.11:8090) - Last seen: 2025-10-05T12:35:01Z
```
## Configuration
### History
Command history is automatically saved to `~/.kvs_history` and persists across sessions.
### Profiles
Profiles are stored in memory during the session. To persist profiles across restarts, you can save them to a configuration file (feature to be added in future versions).
## Authentication
KVS Shell uses JWT tokens for authentication. Obtain a token from your KVS server administrator or through the server's authentication API:
```bash
# Example: Get token from KVS server
curl -X POST http://localhost:8090/api/tokens \
-H "Authorization: Bearer <admin-token>" \
-H "Content-Type: application/json" \
-d '{"user_uuid": "your-uuid", "scopes": ["read", "write"]}'
```
Then use the returned token in the shell:
```
kvs> auth eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
## Advanced Usage
### Working with Complex JSON
For multi-line or complex JSON, use quotes:
```
kvs> put data/user '{"name": "Bob", "preferences": {"theme": "dark", "notifications": true}}'
```
### Key Naming Conventions
Keys can use path-like structures:
```
users/alice
config/app/production
data/metrics/2025-10
```
This helps organize your data hierarchically.
## Troubleshooting
### Connection Issues
If you can't connect to the server:
1. Verify the server is running: `curl http://localhost:8090/health`
2. Check firewall settings
3. Ensure the URL includes the protocol (http:// or https://)
### Authentication Errors
If you get "Unauthorized" errors:
1. Verify your token is still valid (tokens may expire)
2. Check that your user has the required permissions
3. Generate a new token if needed
### Command Not Found
If a command isn't recognized:
- Type `help` to see available commands
- Check for typos in the command name
- Ensure you've connected to a server first
## Development
### Building
```bash
go build -o kvs-shell
```
### Testing
```bash
go test ./...
```
### Dependencies
- `github.com/chzyer/readline` - Interactive line editing and history
- `github.com/fatih/color` - Colored terminal output
## Roadmap
Planned features:
- [ ] Configuration file for persistent profiles
- [ ] Management of local KVS instance configuration file
- [ ] Batch operations from file
- [ ] Export/import functionality
- [ ] Group management commands
- [ ] Metadata management
- [ ] Query filtering and pagination
- [ ] TLS/SSL support
- [ ] Shell scripts execution
- [ ] Tab completion for keys
- [ ] Transaction support