Missing documentation on how to use a S3 service that is not on AWS?

[cglacet]

I wanted to upload a file to a bucket that uses the S3 protocol but is not an AWS endpoint. For example, lets say I wan't to upload to http://{bucket-name}.s3.{region}.{storage_class}.cloud.ovh.net. Where is this documented? To me its something fundamental that many people want to do, it should be very easy to find.

I found the S3 documentation, but it doesn't seem to be the thing I'm looking for, also the S3 client config (but its empty, to be fair its not empty, but its a composed type that is way too complex to be read by a human). I also found this, but it seems unrelated to S3 client Media convert - Specifying Custom Endpoints

All the examples I found use Amazon's endpoint so it seems that in this particular case things are easy.

Using the type hierarchy and after a lot of guessing I think I found how to do it (correct me if I'm wrong):

import { Upload } from '@aws-sdk/lib-storage';
import { S3Client, S3, S3ClientConfig, PutObjectCommandInput } from '@aws-sdk/client-s3';

const s3ClientUrl = new URL(
    `https://s3.${process.env.BUCKET_REGION}.io.cloud.ovh.net`
);

const s3ClientConfig: S3ClientConfig = {
    credentials: {
        accessKeyId: process.env.BUCKET_ACCESS_KEY_ID,
        secretAccessKey: process.env.BUCKET_SECRET_ACCESS_KEY,
    },
    endpoint: {
        url: s3ClientUrl,
    },
};

const client = new S3(s3ClientConfig) || new S3Client(s3ClientConfig);

export async function uploadFile(fileName: string, fileContent: Buffer | string) {
    const params: PutObjectCommandInput = {
        Bucket: process.env.BUCKET_ID,
        Key: fileName,
        Body: fileContent,
    };
    const parallelUploads3 = new Upload({ client, params });
    return await parallelUploads3.done();
}

How I found this:

• autocomplete on S3Client first parameter, by name I found that credentials and endpoint probably were the two things I was looking for (that because I new the python library used endpoint_url to specify the bucket service URL.
• from there I found the type definitions I was looking for:
  • auth documentation : node_modules/@aws-sdk/middleware-signing/dist-types/awsAuthConfiguration.d.ts
  • endpoint's parent documentation: node_modules/@smithy/middleware-endpoint/dist-types/resolveEndpointConfig.d.ts
  • endpoint's documentation: node_modules/@smithy/types/dist-types/http.d.ts
  • endpoint V2's documentation: node_modules/@smithy/types/dist-types/endpoint.d.ts

The type documentation seems to say that V2 is the current version and the Endpoint type is deprecated in favor of EndpointV2:

// File: dist-types/http.d.ts
/**
 * @public
 * @deprecated use {@link EndpointV2} from `@smithy/types`.
 */
export interface Endpoint {
    protocol: string;
    hostname: string;
    port?: number;
    path: string;
    query?: QueryParameterBag;
}

// File: dist-types/endpoint.d.ts
export interface EndpointV2 {
    url: URL;
    properties?: {
        authSchemes?: AuthScheme[];
    } & Record<string, EndpointObjectProperty>;
    headers?: Record<string, string[]>;
}

I haven't tested it yet.