S3Server 6.0.19
dotnet add package S3Server --version 6.0.19
NuGet\Install-Package S3Server -Version 6.0.19
<PackageReference Include="S3Server" Version="6.0.19" />
paket add S3Server --version 6.0.19
#r "nuget: S3Server, 6.0.19"
// Install S3Server as a Cake Addin #addin nuget:?package=S3Server&version=6.0.19 // Install S3Server as a Cake Tool #tool nuget:?package=S3Server&version=6.0.19
S3Server
Simple S3 server-side interface, produced using Amazon's public documentation. Want a simple S3 storage server built using S3Server? Check out Less3.
Feedback and Enhancements
Is there an API you'd like exposed that isn't currently? Did you identify an issue or have other feedback? Please file an issue here!
New in v6.0.x
- Breaking changes with dependency updates
- Moved usings inside of namespaces to reduce collisions
- Moved from
new byte[0]
toArray.Empty<byte>()
- Size limits for
ObjectWrite
(e.g.PutObject
), returnsEntityTooLarge
if exceeded - Boolean for enabling or disabling signature validation
- Added bucket and object callbacks in support of multipart uploads
- Added object callback for S3 Select API
Examples
Refer to Test.Client
and Test.Server
projects for full examples.
Important
The following notes should be read prior to using S3Server:
Path-style URLs are default, i.e.
http://hostname.com/bucket/key
Virtual hosting URLs can be used by setting
S3Server.ServiceCallbacks.FindMatchingBaseDomain
- You must use a wildcard listener (e.g.
*
or+
) and run under administrative privileges - This callback takes one input parameter, the hostname from the HTTP request
- Your implementation should compare the hostname with your list of base domains
- The return value from this method should be the base domain to which the hostname matches
- If no match is found, throw a
KeyNotFoundException
- You may have to set DNS or your
hosts
file to resolve these names accordingly - Alternatively, use a hostname that resolves to localhost (e.g.
[host].local.gd
or[host].fbi.com
) - Any request where the base domain is NOT found in incoming hostname will be treated as a path-style URL request
- You must use a wildcard listener (e.g.
Server
Refer to the Test.Server
project for a more complete example.
using S3ServerLibrary;
using S3ServerLibrary.S3Objects;
// Initialize the server
S3Server server = new S3Server("[hostname]", 8000, false, DefaultRequestHandler); // host, port, SSL
// Set callbacks
server.Service.ListBuckets = ListBuckets;
server.Bucket.Exists = BucketExists;
// etc
// Start the server
server.Start();
// Example callback definition
static async Task DefaultRequestHandler(S3Context ctx)
{
ctx.Response.StatusCode = 400;
ctx.Response.ContentType = Constants.ContentTypeText;
ctx.Response.Send("Bad request");
}
// Callback expecting a response object
static async Task<ListAllMyBucketsResult> ListBuckets(S3Context ctx)
{
return new ListAllMyBucketsResult();
}
static async Task<bool> BucketExists(S3Context ctx)
{
return true;
// throw new S3Exception(new Error(ErrorCode.NoSuchBucket));
}
// Callback passing object to you
static async Task BucketWriteTags(S3Context ctx, Tagging tags)
{
return;
}
Client
Use the following example with the AWSSDK.S3 NuGet package to point your S3 client toward S3Server.
using Amazon;
using Amazon.Runtime;
using Amazon.S3;
using Amazon.S3.Model;
BasicAWSCredentials cred = new Amazon.Runtime.BasicAWSCredentials("access key", "secret key");
AmazonS3Config config = new AmazonS3Config
{
RegionEndpoint = RegionEndpoint.USWest1,
ServiceURL = "http://localhost:8000/",
ForcePathStyle = true, // required if not using virtual hosting style
UseHttp = true
};
IAmazonS3 client = new AmazonS3Client(cred, config);
Request and Responses
An S3Context
object is passed to your callbacks which includes three properties:
S3Request
- the parsed S3 requestS3Response
- the response object with which you will interact to send a responseMetadata
- an object that you can choose to set with your own value- This is often helpful if you use the
PreRequestHandler
for authentication or other purposes
- This is often helpful if you use the
S3Server expects the code you implement in your callbacks to either:
- Respond with a variable (see
S3Server.Bucket.Exists
, expects aBoolean
) - Simply return when no response object is required (see
S3Server.Object.DeleteTagging
) - Throw an
S3Exception
with the appropriateError
object if something goes wrong
Operation
S3Server parses incoming HTTP requests, extracting key pieces of information to determine the type of request sent by the caller. The logic to handle these requests is NOT provided by S3Server; you have to create that logic yourself in your callbacks. Callbacks are called when a request of that type has been received, otherwise, a generic 400 error is returned to the client.
Refer to https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html for the S3 API documentation used to create this project.
The following callbacks are supported:
Service Callbacks
Callback Name | Description | Method | URL |
---|---|---|---|
Service.ListBuckets | List buckets | GET | / |
Service.ServiceExists | Retrieve region for the service | HEAD | / |
Bucket Callbacks
Callback Name | Description | Method | URL |
---|---|---|---|
Bucket.Delete | Delete a bucket | DELETE | /[bucket] |
Bucket.DeleteAcl | Delete ACLs from a bucket | DELETE | /[bucket]?acl |
Bucket.DeleteTagging | Delete tags from a bucket | DELETE | /[bucket]?tagging |
Bucket.DeleteWebsite | Delete bucket website configuration | DELETE | /[bucket]?website |
Bucket.Exists | Check if a bucket exists | HEAD | /[bucket] |
Bucket.Read | Enumerate a bucket | GET | /[bucket] |
Bucket.ReadAcl | Read ACL on a bucket | GET | /[bucket]?acl |
Bucket.ReadLocation | Read a bucket's region | GET | /[bucket]?location |
Bucket.ReadLogging | Read bucket's logging configuration | GET | /[bucket]?logging |
Bucket.ReadTagging | Read tags on a bucket | GET | /[bucket]?tagging |
Bucket.ReadVersioning | Read bucket versioning | GET | /[bucket]?versioning |
Bucket.ReadVersions | Read object versions in a bucket | GET | /[bucket]?versions |
Bucket.ReadWebsite | Read bucket website configuration | GET | /[bucket]?website |
Bucket.Write | Create a bucket | PUT | /[bucket] |
Bucket.WriteAcl | Write an ACL to a bucket | PUT | /[bucket]?acl |
Bucket.WriteLogging | Write bucket logging configuration | PUT | /[bucket]?logging |
Bucket.WriteTagging | Write tags to a bucket | PUT | /[bucket]?tagging |
Bucket.WriteVersioning | Write bucket versioning | PUT | /[bucket]?versioning |
Bucket.WriteWebsite | Write bucket website configuration | PUT | /[bucket]?website |
Object Callbacks
Callback Name | Description | Method | URL |
---|---|---|---|
Object.Delete | Delete an object | DELETE | /[bucket]/[key] |
Object.DeleteTagging | Delete an object's tags | DELETE | /[bucket]/[key]?tagging |
Object.DeleteMultiple | Delete multiple objects | POST | /[bucket]?delete^2 |
Object.Exists | Check if an object exists | HEAD | /[bucket]/[key] |
Object.Write | Write an object | PUT | /[bucket]/[key] |
Object.WriteAcl | Write an object access control list | PUT | /[bucket]/[key]?acl |
Object.WriteTagging | Write tags to an object | PUT | /[bucket]/[key]?tagging |
Object.WriteLegalHold | Write a legal hold status to an object | PUT | /[bucket]/[key]?legal-hold |
Object.WriteRetention | Write a retention status to an object | PUT | /[bucket]/[key]?retention |
Object.Read | Read an object | GET | /[bucket]/[key] |
Object.ReadAcl | Read an object's access control list | GET | /[bucket]/[key]?acl |
Object.ReadLegalHold | Read an object's legal hold status | GET | /[bucket]/[key]?legal-hold |
Object.ReadRange | Read a range of bytes from an object | GET | /[bucket]/[key]^1 |
Object.ReadRetention | Read an object's retention status | GET | /[bucket]/[key]?retention |
Object.ReadTagging | Read an object's tags | GET | /[bucket]/[key]?tagging |
^1 Refer to the Bytes header in S3Request.Headers
for the range that should be retrieved.
^2 A delete multiple request body must be supplied.
Unsupported / Not Yet Available
Operations against the service or AWS accounts is not exposed through callbacks.
The following bucket operations are not exposed through callbacks:
- Accelerate
- Analytics
- CORS
- Encryption
- Inventory
- Lifecycle
- Notification
- Object lock configuration
- Object versions
- Policy status
- Public access block
- Metrics
- Payment
- Policy
- Replication
The following object operations are not exposed through callbacks:
- Multipart upload
- Parts
- Restore
- Torrent
The following general capabilities are not yet supported by S3Server
- Validation of chunk signatures
These items may be addressed in a future release.
Version History
Refer to CHANGELOG.md for details.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net6.0
- AWSSignatureGenerator (>= 1.0.8)
- PrettyId (>= 1.0.2)
- Watson (>= 6.3.0)
-
net8.0
- AWSSignatureGenerator (>= 1.0.8)
- PrettyId (>= 1.0.2)
- Watson (>= 6.3.0)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on S3Server:
Package | Downloads |
---|---|
Less3
<3 Less3 is S3-compatible object storage that you can run on your laptop, server, or anywhere you like. |
|
View.Models
View.io is currently in BETA. Database models and supporting classes for View.io services. |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
6.0.19 | 93 | 12/13/2024 |
6.0.18 | 203 | 9/9/2024 |
6.0.17 | 96 | 9/9/2024 |
6.0.16 | 146 | 8/6/2024 |
6.0.15 | 82 | 8/2/2024 |
6.0.14 | 318 | 7/7/2024 |
6.0.12 | 142 | 4/20/2024 |
6.0.11 | 139 | 4/4/2024 |
6.0.10 | 133 | 3/28/2024 |
6.0.9 | 122 | 3/28/2024 |
6.0.8 | 4,320 | 1/2/2024 |
6.0.7 | 114 | 1/2/2024 |
6.0.6 | 127 | 1/2/2024 |
6.0.5 | 125 | 1/2/2024 |
6.0.4 | 120 | 1/2/2024 |
6.0.3 | 158 | 12/14/2023 |
6.0.2 | 175 | 11/27/2023 |
6.0.1 | 126 | 11/27/2023 |
6.0.0 | 133 | 11/14/2023 |
5.3.2 | 215 | 8/31/2023 |
5.3.1 | 1,297 | 8/24/2023 |
5.2.2 | 384 | 8/19/2023 |
5.2.1 | 162 | 8/19/2023 |
5.1.9 | 594 | 8/1/2023 |
5.1.8 | 1,959 | 5/18/2023 |
5.1.7 | 161 | 5/18/2023 |
5.1.6 | 301 | 5/11/2023 |
5.1.5 | 154 | 5/9/2023 |
5.1.4 | 162 | 5/9/2023 |
5.1.3 | 159 | 5/9/2023 |
5.1.2 | 159 | 5/8/2023 |
5.1.1 | 195 | 4/18/2023 |
5.1.0 | 200 | 4/13/2023 |
5.0.16 | 2,046 | 10/12/2022 |
5.0.15 | 407 | 10/12/2022 |
5.0.14 | 651 | 10/7/2022 |
5.0.13 | 362 | 10/7/2022 |
5.0.12 | 385 | 10/7/2022 |
5.0.11 | 1,420 | 9/22/2022 |
5.0.10 | 453 | 9/22/2022 |
5.0.9 | 457 | 9/22/2022 |
5.0.8 | 694 | 9/21/2022 |
5.0.7 | 635 | 9/20/2022 |
5.0.6 | 1,054 | 9/15/2022 |
5.0.5 | 461 | 9/15/2022 |
5.0.4 | 720 | 9/14/2022 |
5.0.3 | 477 | 9/14/2022 |
5.0.2 | 507 | 9/14/2022 |
5.0.1 | 556 | 9/13/2022 |
5.0.0 | 540 | 9/13/2022 |
4.0.1.13 | 1,480 | 4/1/2022 |
4.0.1.12 | 652 | 4/1/2022 |
4.0.1.11 | 653 | 3/31/2022 |
4.0.1.10 | 448 | 3/30/2022 |
4.0.1.9 | 627 | 3/30/2022 |
4.0.1.8 | 463 | 1/27/2022 |
4.0.1.7 | 464 | 1/26/2022 |
4.0.1.6 | 1,735 | 10/25/2021 |
4.0.1.5 | 416 | 10/22/2021 |
4.0.1.4 | 370 | 10/22/2021 |
4.0.1.3 | 379 | 10/20/2021 |
4.0.1.2 | 417 | 10/14/2021 |
4.0.1.1 | 368 | 10/13/2021 |
4.0.1 | 373 | 10/13/2021 |
3.2.5 | 1,616 | 7/9/2021 |
3.2.4 | 487 | 6/15/2021 |
3.2.3 | 507 | 6/15/2021 |
3.2.2 | 353 | 6/15/2021 |
3.2.1 | 367 | 6/15/2021 |
3.2.0 | 348 | 6/15/2021 |
3.1.2 | 360 | 6/11/2021 |
3.1.1 | 1,225 | 4/20/2021 |
3.1.0 | 796 | 3/9/2021 |
3.0.2 | 363 | 3/9/2021 |
3.0.1 | 410 | 3/9/2021 |
3.0.0 | 412 | 3/5/2021 |
Dependency update and change to base domains.