Package Exports

zephyr-agent
zephyr-agent/node-persist

Readme

Zephyr Agent (Internal)

Zephyr Cloud | Zephyr Docs | Discord | Twitter | LinkedIn

Internal Package - The main internal package that provides the Zephyr agent for bundler plugins. This package contains the core functionality for deployment, asset management, and communication with Zephyr Cloud.

Note: This is an internal package used by other Zephyr plugins. It is not intended for direct use by end users.

Overview

The Zephyr Agent is the core engine that powers all Zephyr bundler plugins. It provides:

Deployment Pipeline: Handles the complete deployment workflow to Zephyr Cloud
Asset Management: Optimizes and manages build assets for edge distribution
Authentication: Manages secure communication with Zephyr Cloud services
Build Context: Provides build-time context and metadata for plugins
Edge Communication: Handles communication with Zephyr's edge network

Architecture

The agent is structured into several key modules:

Authentication (`lib/auth/`)

Handles user authentication and authorization
Manages API tokens and session management
Provides WebSocket connections for real-time updates

Build Context (`lib/build-context/`)

Extracts build metadata and package information
Provides Git integration and repository context
Manages dependency resolution and parsing

Deployment (`lib/deployment/`)

Implements deployment strategies for different CDN providers
Supports Cloudflare, Fastly, and Netlify deployment targets
Handles asset uploads and build stats publication

Edge Actions (`lib/edge-actions/`)

Manages deployment operations on edge infrastructure
Handles snapshot creation and environment enabling
Coordinates asset uploads and build statistics

HTTP Layer (`lib/http/`)

Provides HTTP client functionality with retries
Handles file uploads and API communication
Manages request/response lifecycle

Usage by Plugins

Public Zephyr plugins interact with the agent through well-defined APIs:

import { ZephyrAgent } from 'zephyr-agent';

// Initialize the agent
const agent = new ZephyrAgent({
  buildContext: buildInfo,
  assets: assetMap,
});

// Deploy to Zephyr Cloud
await agent.deploy();

Dependencies

The agent has minimal external dependencies:

Core Dependencies: Node.js built-ins and essential utilities
Network: HTTP client libraries for API communication
File System: Asset management and build context extraction
Crypto: Secure token management and validation

Configuration

The agent is configured through build context and environment variables:

interface ZephyrAgentConfig {
  buildContext: BuildContext;
  assets: AssetMap;
  deploymentOptions?: DeploymentOptions;
  authentication?: AuthConfig;
}

Internal APIs

Build Context API

// Extract package.json information
const packageInfo = await readPackageJson(projectRoot);

// Get Git repository information
const gitInfo = await getGitInfo();

// Parse Zephyr dependencies
const deps = parseZephyrDependencies(packageJson);

Deployment API

// Upload assets to CDN
await uploadAssets(assets, uploadStrategy);

// Enable environment on edge
await enableSnapshotOnEdge(snapshotId);

// Upload build statistics
await uploadBuildStats(buildStats);

Integration Points

The agent integrates with:

Bundler Plugins: Receives build assets and metadata
Zephyr Cloud: Deploys assets and manages deployments
CDN Providers: Uploads assets to edge locations
Git Providers: Extracts repository and commit information

Development

For plugin developers working on Zephyr integrations:

# Build the agent
npm run build

# Run tests
npm run test

# Development mode
npm run dev

Security

The agent implements several security measures:

Token Management: Secure storage and rotation of API tokens
Encrypted Communication: All API communication uses HTTPS/WSS
Input Validation: Validates all build inputs and configurations
Access Control: Role-based access to deployment operations

Contributing

This is an internal package. Contributions should be made through the main Zephyr plugins repository. Please read our contributing guidelines for more information.

License

Licensed under the Apache-2.0 License. See LICENSE for more information.

zephyr-agent