or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

bucket.md client.md cluster.md image.md index.md multipart.md object.md rtmp.md sts.md

tile.json

Client Configuration

The OSS client is the main entry point for all interactions with Alibaba Cloud Object Storage Service. It provides authentication, connection management, and serves as the base for all other operations.

Core Client Setup

Basic Client Creation

function OSS(options: ClientOptions, ctx?: ClientContext): OSSClient;

interface ClientOptions {
  region?: string;
  accessKeyId: string;
  accessKeySecret: string;
  stsToken?: string;
  bucket?: string;
  endpoint?: string;
  internal?: boolean;
  secure?: boolean;
  timeout?: number | number[];
  cname?: boolean;
  isRequestPay?: boolean;
  agent?: Agent;
  httpsAgent?: Agent;
  maxSockets?: number;
  retryMax?: number;
  retryDelay?: number;
  urllib?: any;
  headers?: Record<string, string>;
  headerEncoding?: string;
  cloudBoxId?: string;
  refreshSTSToken?: () => Promise<STSCredentials>;
  requestErrorRetryHandle?: (error: Error, retryCount: number) => boolean;
}

interface STSCredentials {
  accessKeyId: string;
  accessKeySecret: string;
  stsToken: string;
}

interface ClientContext {
  [key: string]: any;
}

Standard Configuration

const OSS = require('ali-oss');

// Basic configuration
const client = new OSS({
  region: 'oss-cn-hangzhou',
  accessKeyId: 'your-access-key-id',
  accessKeySecret: 'your-access-key-secret',
  bucket: 'your-bucket-name'
});

// Configuration with custom endpoint
const client = new OSS({
  accessKeyId: 'your-access-key-id',
  accessKeySecret: 'your-access-key-secret',
  endpoint: 'https://oss-cn-beijing.aliyuncs.com',
  bucket: 'your-bucket-name'
});

// Configuration with STS token
const client = new OSS({
  region: 'oss-cn-hangzhou',
  accessKeyId: 'your-sts-access-key',
  accessKeySecret: 'your-sts-access-secret',
  stsToken: 'your-sts-token',
  bucket: 'your-bucket-name'
});

Authentication Methods

AccessKey Authentication

interface AccessKeyConfig {
  region: string;
  accessKeyId: string;
  accessKeySecret: string;
  bucket?: string;
}

STS Token Authentication

interface STSTokenConfig {
  region: string;
  accessKeyId: string;
  accessKeySecret: string;
  stsToken: string;
  bucket?: string;
}

Connection Configuration

HTTP Agent Settings

interface AgentConfig {
  agent?: Agent;
  httpsAgent?: Agent;
  maxSockets?: number;
  timeout?: number | number[];
}

const http = require('http');
const https = require('https');

const client = new OSS({
  region: 'oss-cn-hangzhou',
  accessKeyId: 'your-access-key-id',
  accessKeySecret: 'your-access-key-secret',
  agent: new http.Agent({ keepAlive: true }),
  httpsAgent: new https.Agent({ keepAlive: true }),
  maxSockets: 20,
  timeout: [60000, 120000] // [connection timeout, response timeout]
});

Retry Configuration

interface RetryConfig {
  retryMax?: number;
  retryDelay?: number;
}

const client = new OSS({
  region: 'oss-cn-hangzhou',
  accessKeyId: 'your-access-key-id',
  accessKeySecret: 'your-access-key-secret',
  retryMax: 3,
  retryDelay: 1000
});

Client Instance Methods

Authentication & Signature

signature(stringToSign: string): string;
authorization(method: string, resource: string, subres?: string, headers?: Record<string, string>): string;
authorizationV4(method: string, requestParams: V4RequestParams, bucketName?: string, objectName?: string, additionalHeaders?: Record<string, string>): string;

interface V4RequestParams {
  headers: Record<string, string>;
  queries: Record<string, string>;
  date: Date;
}

Request Handling

async request(params: RequestParams): Promise<RequestResult>;

interface RequestParams {
  method: string;
  uri: string;
  headers?: Record<string, string>;
  content?: any;
  timeout?: number | number[];
  ctx?: any;
}

interface RequestResult {
  status: number;
  headers: Record<string, string>;
  data?: any;
  res: any;
}

Utility Methods

parseXML(str: string): Promise<any>;
requestError(result: RequestResult): Error;
setSLDEnabled(enable: boolean): void;
checkBrowserAndVersion(name: string, version: string): boolean;

Configuration Options Details

Region and Endpoint

region: OSS service region (e.g., 'oss-cn-hangzhou', 'oss-us-west-1')
endpoint: Custom endpoint URL, overrides region-based endpoint
internal: Use internal endpoint (for ECS instances in same region)
secure: Use HTTPS (default: true)
cname: Use custom domain name

Authentication

accessKeyId: Alibaba Cloud Access Key ID
accessKeySecret: Alibaba Cloud Access Key Secret
stsToken: Security Token Service token for temporary access

Performance and Reliability

timeout: Request timeout in milliseconds, can be array [connect, response]
retryMax: Maximum number of retry attempts (default: 3)
retryDelay: Delay between retries in milliseconds (default: 1000)
maxSockets: Maximum number of concurrent connections per host

Headers and Options

headers: Default headers to include with all requests
isRequestPay: Enable requester pays mode
urllib: Custom HTTP client library
headerEncoding: Character encoding for headers (default: 'utf8')
cloudBoxId: Cloud box identifier for private cloud deployments
refreshSTSToken: Function to automatically refresh STS token when needed
requestErrorRetryHandle: Custom function to determine if a request should be retried

Browser-Specific Configuration

Browser Client Creation

// Browser global
const client = new OSS({
  region: 'oss-cn-hangzhou',
  accessKeyId: 'your-access-key-id',
  accessKeySecret: 'your-access-key-secret',
  bucket: 'your-bucket-name'
});

// Additional browser properties
interface BrowserClientOptions extends ClientOptions {
  // Browser-specific options are handled automatically
}

CORS Requirements

For browser usage, ensure your OSS bucket has appropriate CORS configuration:

<CORSRule>
  <AllowedOrigin>*</AllowedOrigin>
  <AllowedMethod>GET</AllowedMethod>
  <AllowedMethod>PUT</AllowedMethod>
  <AllowedMethod>POST</AllowedMethod>
  <AllowedMethod>DELETE</AllowedMethod>
  <AllowedMethod>HEAD</AllowedMethod>
  <AllowedHeader>*</AllowedHeader>
</CORSRule>

Static Methods

Client Factory Methods

static initOptions(options: ClientOptions): ClientOptions;
static ImageClient: typeof ImageClient;
static ClusterClient: typeof ClusterClient;
static STS: typeof STS;

Error Handling

Client Errors

interface OSSError extends Error {
  name: string;
  message: string;
  code?: string;
  status?: number;
  headers?: Record<string, string>;
  requestId?: string;
  hostId?: string;
}

Common error scenarios:

Invalid credentials (403 Forbidden)
Network connectivity issues
Invalid region or endpoint
Request timeout
Service-side errors (5xx status codes)