pbar.io

Core Concepts

Understand the fundamental concepts and architecture of pbar.io.

Progress Bar Lifecycle

States and Transitions

Created

Initial state when a progress bar is created. Sets up slug, URLs, and initial values.

Active

Progress bar is being updated. Tracks start time, calculates rate and ETA.

Completed

Progress reaches 100% or explicitly marked complete. Records completion time.

Cancelled

Progress bar cancelled before completion. Cascades to all child bars.

Expired

Free tier bars expire after 30 days. Data is deleted automatically.

Timing Calculations

  • Elapsed Time: Calculated from started_at timestamp
  • Rate: Items processed per second, updated with each increment
  • ETA: Estimated time remaining based on current rate
  • Completion: Automatically set when current equals total

Hierarchical Progress Bars

pbar.io supports nested progress bars with automatic aggregation, perfect for complex multi-stage processes.

Parent-Child Relationships

Automatic Aggregation

Parent bars automatically calculate their progress based on child completion:

Parent Total = Number of child bars
Parent Current = Number of completed (non-cancelled) children

Nesting Depth

Maximum nesting depth: 5 levels. This prevents excessive complexity while supporting sophisticated workflows.

Cascade Operations

  • Cancelling a parent cancels all children
  • Deleting a parent deletes all descendants
  • Parent shows "incomplete" status if any child is cancelled
  • Completion doesn't cascade (children complete independently)

Use Cases

  • Multi-stage pipelines with sub-tasks
  • Batch processing with item-level progress
  • Deployment workflows across environments
  • Parallel task execution with aggregated view

Access Control & Privacy

Public Bars (Default)

  • ✓Viewable by anyone with the URL
  • ✓Updatable by anyone (if writable)
  • ✓No authentication required
  • !Expire after 30 days

Private Bars (API Key)

  • 🔒Require API key to view/update
  • 🔒Can be made read-only
  • 🔒No expiration
  • 🔒Higher rate limits

⚠️ Security Note

URLs are unguessable (7-character random slugs = 3.5 trillion combinations), but treat them as sensitive if they contain private information. Use API keys for truly sensitive data.

Rate Limiting

Rate limits ensure fair usage and system stability. Limits are per IP address for anonymous users.

Free Tier Limits

OperationLimitWindow
Create (POST)100 requestsPer hour
Update (PATCH)1,000 requestsPer hour
Read (GET)Unlimited-
Delete (DELETE)100 requestsPer hour

Rate Limit Headers

  • X-RateLimit-Limit - Total allowed
  • X-RateLimit-Remaining - Requests left
  • X-RateLimit-Reset - Reset timestamp

Handling 429 Errors

  • Implement exponential backoff
  • Batch updates when possible
  • Use client libraries (automatic retry)

Data Storage & Expiration

Storage Policies

Free Tier (Anonymous)

  • Data stored for 30 days from creation
  • Automatic deletion after expiration
  • No recovery after deletion
  • IP addresses hashed for privacy

Authenticated Tier

  • No automatic expiration
  • Manual deletion required
  • Data export available
  • Audit logs maintained

Metadata Storage

  • Any JSON-serializable data
  • Maximum size: 1KB per bar
  • Updated with each PATCH request
  • Included in all responses

Real-time Updates

Progress bars support real-time updates via WebSockets, enabling instant synchronization across all viewers.

WebSocket Features

Automatic Subscriptions

Web viewers automatically subscribe to updates. No configuration needed.

Event Types

  • Progress updates
  • Metadata changes
  • Completion/cancellation
  • Child bar changes

Connection Management

Automatic reconnection on network issues. Buffered updates during disconnection.

Performance

Updates throttled to max 10/second per bar. Batching for high-frequency updates.

Terminal Live View

Watch progress in terminal with automatic refresh:

while true; do printf '\r'; curl -s https://pbar.io/api/bars/YOUR_SLUG; sleep 1; done

API Design Principles

RESTful Design

Standard HTTP methods, status codes, and resource-based URLs for predictable behavior.

Content Negotiation

Automatic format selection based on Accept header and User-Agent detection.

Idempotent Updates

Use increment for safe concurrent updates. Multiple identical requests = same result.

Graceful Degradation

Progress tracking failures never break your application. Optional at every level.