Update README.md with wiki links
This commit is contained in:
vesp
parent
c09a5515a7
commit
d7a336e524
234
README.md
234
README.md
@ -6,187 +6,117 @@ A modern HTTP client for GNOME, built with GTK 4 and libadwaita.
|
|||||||
|
|
||||||
- Send HTTP requests (GET, POST, PUT, DELETE)
|
- Send HTTP requests (GET, POST, PUT, DELETE)
|
||||||
- Configure custom headers and request bodies
|
- Configure custom headers and request bodies
|
||||||
- View response headers and bodies
|
- View response headers and bodies with syntax highlighting
|
||||||
- Track request history with persistence
|
- Track request history with persistence
|
||||||
- **JavaScript preprocessing and postprocessing scripts**
|
- Organize requests into projects
|
||||||
- **Project environments with variables**
|
- Environment variables with secure credential storage
|
||||||
|
- JavaScript preprocessing and postprocessing scripts
|
||||||
|
- Export requests (cURL and more)
|
||||||
- Beautiful GNOME-native UI
|
- Beautiful GNOME-native UI
|
||||||
|
|
||||||
## Dependencies
|
## Quick Start
|
||||||
|
|
||||||
- GTK 4
|
### Installation
|
||||||
- libadwaita 1
|
|
||||||
- Python 3
|
|
||||||
- libsoup3 (provided by GNOME Platform)
|
|
||||||
- gjs (GNOME JavaScript) - for script execution
|
|
||||||
|
|
||||||
## Building
|
|
||||||
|
|
||||||
|
**Build from source:**
|
||||||
```bash
|
```bash
|
||||||
|
git clone https://git.bugsy.cz/beval/roster.git
|
||||||
|
cd roster
|
||||||
meson setup builddir
|
meson setup builddir
|
||||||
meson compile -C builddir
|
meson compile -C builddir
|
||||||
sudo meson install -C builddir
|
sudo meson install -C builddir
|
||||||
```
|
```
|
||||||
|
|
||||||
## Usage
|
**Flatpak:**
|
||||||
|
```bash
|
||||||
Roster uses libsoup3 (from GNOME Platform) for making HTTP requests - no external dependencies required.
|
flatpak-builder --user --install --force-clean build-dir cz.bugsy.roster.json
|
||||||
|
flatpak run cz.bugsy.roster
|
||||||
Run Roster from your application menu or with the `roster` command.
|
|
||||||
|
|
||||||
## Scripts
|
|
||||||
|
|
||||||
Roster supports JavaScript preprocessing and postprocessing scripts to automate request modifications and response data extraction.
|
|
||||||
|
|
||||||
### Preprocessing Scripts
|
|
||||||
|
|
||||||
**Run BEFORE the HTTP request is sent.** Use preprocessing to:
|
|
||||||
- Modify request headers, URL, body, or method
|
|
||||||
- Add dynamic values (timestamps, request IDs, signatures)
|
|
||||||
- Read environment variables
|
|
||||||
- Set/update environment variables
|
|
||||||
|
|
||||||
**Available API:**
|
|
||||||
```javascript
|
|
||||||
// Request object (modifiable)
|
|
||||||
request.method // "GET", "POST", "PUT", "DELETE"
|
|
||||||
request.url // Full URL string
|
|
||||||
request.headers // Object with header key-value pairs
|
|
||||||
request.body // Request body string
|
|
||||||
|
|
||||||
// Roster API
|
|
||||||
roster.getVariable(name) // Get variable from selected environment
|
|
||||||
roster.setVariable(name, value) // Set/update variable
|
|
||||||
roster.setVariables({key: value}) // Batch set variables
|
|
||||||
roster.project.name // Current project name
|
|
||||||
roster.project.environments // Array of environment names
|
|
||||||
|
|
||||||
// Console output
|
|
||||||
console.log(message) // Output shown in preprocessing results
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Example 1: Add Dynamic Authentication Header**
|
See the [Installation Guide](https://git.bugsy.cz/beval/roster/wiki/Installation) for detailed instructions.
|
||||||
```javascript
|
|
||||||
const token = roster.getVariable('auth_token');
|
|
||||||
request.headers['Authorization'] = 'Bearer ' + token;
|
|
||||||
request.headers['X-Request-Time'] = new Date().toISOString();
|
|
||||||
console.log('Added auth header for token:', token);
|
|
||||||
```
|
|
||||||
|
|
||||||
**Example 2: Modify Request Based on Environment**
|
### Usage
|
||||||
```javascript
|
|
||||||
const env = roster.getVariable('environment_name');
|
|
||||||
if (env === 'production') {
|
|
||||||
request.url = request.url.replace('localhost', 'api.example.com');
|
|
||||||
console.log('Switched to production URL');
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Example 3: Generate Request Signature**
|
Launch Roster from your application menu or run `roster` from the command line.
|
||||||
```javascript
|
|
||||||
const apiKey = roster.getVariable('api_key');
|
|
||||||
const timestamp = Date.now().toString();
|
|
||||||
const requestId = Math.random().toString(36).substring(7);
|
|
||||||
|
|
||||||
request.headers['X-API-Key'] = apiKey;
|
See the [Getting Started Guide](https://git.bugsy.cz/beval/roster/wiki/Getting-Started) for a walkthrough.
|
||||||
request.headers['X-Timestamp'] = timestamp;
|
|
||||||
request.headers['X-Request-ID'] = requestId;
|
|
||||||
|
|
||||||
// Save for later reference
|
## Documentation
|
||||||
roster.setVariable('last_request_id', requestId);
|
|
||||||
console.log('Request ID:', requestId);
|
|
||||||
```
|
|
||||||
|
|
||||||
### Postprocessing Scripts
|
Complete documentation is available in the [Wiki](https://git.bugsy.cz/beval/roster/wiki):
|
||||||
|
|
||||||
**Run AFTER receiving the HTTP response.** Use postprocessing to:
|
- **[Home](https://git.bugsy.cz/beval/roster/wiki/Home)** - Overview and quick links
|
||||||
- Extract data from response body
|
- **[Installation](https://git.bugsy.cz/beval/roster/wiki/Installation)** - Build and install instructions
|
||||||
- Parse JSON/XML responses
|
- **[Getting Started](https://git.bugsy.cz/beval/roster/wiki/Getting-Started)** - Your first HTTP request
|
||||||
- Store values in environment variables for use in subsequent requests
|
- **[Projects and Environments](https://git.bugsy.cz/beval/roster/wiki/Projects-and-Environments)** - Organize your work
|
||||||
- Validate response data
|
- **[Variables](https://git.bugsy.cz/beval/roster/wiki/Variables)** - Use variables in requests
|
||||||
|
- **[Sensitive Variables](https://git.bugsy.cz/beval/roster/wiki/Sensitive-Variables)** - Secure credential storage with GNOME Keyring
|
||||||
|
- **[Scripts](https://git.bugsy.cz/beval/roster/wiki/Scripts)** - Automate workflows with JavaScript
|
||||||
|
- **[API Reference](https://git.bugsy.cz/beval/roster/wiki/API-Reference)** - Complete JavaScript API
|
||||||
|
- **[Keyboard Shortcuts](https://git.bugsy.cz/beval/roster/wiki/Keyboard-Shortcuts)** - Speed up your workflow
|
||||||
|
- **[FAQ](https://git.bugsy.cz/beval/roster/wiki/FAQ)** - Frequently asked questions
|
||||||
|
|
||||||
**Available API:**
|
## Key Features
|
||||||
```javascript
|
|
||||||
// Response object (read-only)
|
|
||||||
response.body // Response body as string
|
|
||||||
response.headers // Object with header key-value pairs
|
|
||||||
response.statusCode // HTTP status code (e.g., 200, 404)
|
|
||||||
response.statusText // Status text (e.g., "OK", "Not Found")
|
|
||||||
response.responseTime // Response time in milliseconds
|
|
||||||
|
|
||||||
// Roster API
|
### Secure Credential Storage
|
||||||
roster.setVariable(name, value) // Set/update variable
|
|
||||||
roster.setVariables({key: value}) // Batch set variables
|
|
||||||
|
|
||||||
// Console output
|
Store API keys, passwords, and tokens securely in GNOME Keyring with one-click encryption. Regular variables are stored in JSON, while sensitive variables are encrypted.
|
||||||
console.log(message) // Output shown in script results
|
|
||||||
```
|
|
||||||
|
|
||||||
**Example 1: Extract Authentication Token**
|
[Learn more about Sensitive Variables](https://git.bugsy.cz/beval/roster/wiki/Sensitive-Variables)
|
||||||
```javascript
|
|
||||||
const data = JSON.parse(response.body);
|
|
||||||
if (data.access_token) {
|
|
||||||
roster.setVariable('auth_token', data.access_token);
|
|
||||||
console.log('Saved auth token');
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Example 2: Extract Multiple Values**
|
### JavaScript Automation
|
||||||
```javascript
|
|
||||||
const data = JSON.parse(response.body);
|
|
||||||
roster.setVariables({
|
|
||||||
user_id: data.user.id,
|
|
||||||
user_name: data.user.name,
|
|
||||||
session_id: data.session.id
|
|
||||||
});
|
|
||||||
console.log('Extracted user:', data.user.name);
|
|
||||||
```
|
|
||||||
|
|
||||||
**Example 3: Validate and Store Response**
|
Use preprocessing and postprocessing scripts to:
|
||||||
```javascript
|
- Extract authentication tokens from responses
|
||||||
const data = JSON.parse(response.body);
|
- Add dynamic headers (timestamps, signatures)
|
||||||
if (response.statusCode === 200 && data.items) {
|
- Chain requests together
|
||||||
roster.setVariable('item_count', data.items.length.toString());
|
- Validate responses
|
||||||
if (data.items.length > 0) {
|
|
||||||
roster.setVariable('first_item_id', data.items[0].id);
|
|
||||||
}
|
|
||||||
console.log('Found', data.items.length, 'items');
|
|
||||||
} else {
|
|
||||||
console.log('Error: Invalid response');
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Workflow Example: OAuth Token Flow
|
[Learn more about Scripts](https://git.bugsy.cz/bavel/roster/wiki/Scripts)
|
||||||
|
|
||||||
**Request 1 (Login) - Postprocessing:**
|
### Multi-Environment Support
|
||||||
```javascript
|
|
||||||
// Extract and store tokens from login response
|
|
||||||
const data = JSON.parse(response.body);
|
|
||||||
roster.setVariables({
|
|
||||||
access_token: data.access_token,
|
|
||||||
refresh_token: data.refresh_token,
|
|
||||||
user_id: data.user_id
|
|
||||||
});
|
|
||||||
console.log('Logged in as user:', data.user_id);
|
|
||||||
```
|
|
||||||
|
|
||||||
**Request 2 (API Call) - Preprocessing:**
|
Manage multiple environments (development, staging, production) with different variable values. Switch environments with one click.
|
||||||
```javascript
|
|
||||||
// Use stored token in subsequent request
|
|
||||||
const token = roster.getVariable('access_token');
|
|
||||||
const userId = roster.getVariable('user_id');
|
|
||||||
|
|
||||||
request.headers['Authorization'] = 'Bearer ' + token;
|
[Learn more about Variables](https://git.bugsy.cz/beval/roster/wiki/Variables)
|
||||||
request.url = request.url.replace('{userId}', userId);
|
|
||||||
console.log('Making authenticated request for user:', userId);
|
|
||||||
```
|
|
||||||
|
|
||||||
### Environment Variables
|
## Dependencies
|
||||||
|
|
||||||
Variables can be:
|
### Runtime
|
||||||
- Manually defined in "Manage Environments"
|
- GTK 4
|
||||||
- Automatically created by scripts using `roster.setVariable()`
|
- libadwaita 1
|
||||||
- Used in requests with `{{variable_name}}` syntax
|
- Python 3
|
||||||
- Read in preprocessing with `roster.getVariable()`
|
- libsoup3 (provided by GNOME Platform)
|
||||||
|
- libsecret (provided by GNOME Platform)
|
||||||
|
- GJS (GNOME JavaScript)
|
||||||
|
|
||||||
Variables are scoped to environments within projects, allowing different values for development, staging, and production.
|
### Build
|
||||||
|
- Meson (>= 1.0.0)
|
||||||
|
- Ninja
|
||||||
|
- pkg-config
|
||||||
|
- gettext
|
||||||
|
|
||||||
|
See the [Installation Guide](https://git.bugsy.cz/beval/roster/wiki/Installation) for platform-specific dependencies.
|
||||||
|
|
||||||
|
## Platform
|
||||||
|
|
||||||
|
Roster is built specifically for the GNOME desktop using native technologies:
|
||||||
|
- **GTK 4** - Modern UI toolkit
|
||||||
|
- **libadwaita** - GNOME design patterns
|
||||||
|
- **libsoup3** - HTTP networking
|
||||||
|
- **libsecret** - Secure credential storage
|
||||||
|
- **GJS** - JavaScript runtime for scripts
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
GPL-3.0-or-later
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
- **Issues**: [git.bugsy.cz/beval/roster/issues](https://git.bugsy.cz/beval/roster/issues)
|
||||||
|
- **Wiki**: [git.bugsy.cz/beval/roster/wiki](https://git.bugsy.cz/bavel/roster/wiki)
|
||||||
|
- **Source**: [git.bugsy.cz/beval/roster](https://git.bugsy.cz/beval/roster)
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
Contributions are welcome! Please open an issue or pull request.
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user