Cloud Services and Callbacks

Integrate object storage, cloud communication and WeChat services, and correctly handle callback verification and repeated notifications.

The cloud adapter integrates the remote protocol framework, but the configuration, calling permissions and business completion conditions still need to be clearly defined by the application. Reading a storage object, sending notifications, and receiving payment callbacks cannot use the same retry or confirmation strategy.

Capability and Configuration Portal

Expand	Current main capabilities	Configuration location
Amazon	S3 and compatible object storage	/Externals/Amazon/ConnectionSettings
Aliyun	OSS, messaging, SMS/voice, mobile push	Corresponding service settings for /Externals/Aliyun
Wechat	Accounts, public platforms, third-party platforms and payment adaptation	Included accounts, certificates and service options

Each main package and Web/API/Gateway are different deployment products. There is no need to deploy a callback gateway when you only need to access storage; when you need to receive callbacks, just installing the client main package will not automatically provide an HTTP entry.

Object Storage Basics

Object storage locates data by Bucket and Key, and directories are usually just key prefixes. The framework file system provides a unified path, but behaviors such as renaming, appending, enumerating, and random writing may not be the same as local disks.

Amazon plugin registration zfs.s3, the basePath of Discussions.option is zfs.s3:/zongsoft-discussions/, where zongsoft-discussions is the Bucket configured by this module. Aliyun OSS uses zfs.oss. Bucket selection and Key prefix should be subject to business permissions, and do not use the full path provided by the user directly for cross-tenant access.

The long text of Discussions is saved as an external file by ContentType and written by Utility.WriteTextFile via the unified file system. path is generated by module path rules, not any external input; this method will create or overwrite the target, and the application must prepare its own test Bucket and credentials before running.

Source: src/Utility.cs (excerpt; see source for context).

Utility.cs

public static bool WriteTextFile(string path, string content)
{
	if(string.IsNullOrWhiteSpace(path))
		throw new ArgumentNullException(nameof(path));

	if(string.IsNullOrWhiteSpace(content))
		return false;

	using(var stream = FileSystem.File.Open(path, FileMode.Create, FileAccess.Write))
	{
		using(var writer = new StreamWriter(stream, System.Text.Encoding.UTF8))
		{
			writer.Write(content);
		}
	}

	return true;
}

The Amazon connection driver is amazon.s3, which supports region, endpoint, and credential configuration; custom endpoints will use path addressing. Whether the service account has the required operation permissions should be verified on dedicated resources. The using above ensures that the writer and stream are released. The module's MutateContentAsync cleans up new files when database writing fails, see Transactions and Consistency for details; such file operations are still synchronous calls. Just because the outer data service is an asynchronous method does not mean that all underlying storage operations are non-blocking.

Aliyun Service Configuration

general Select the service center and internal and external network, and the named certificate saves the access credentials; Bucket, message, communication template and push application can select the corresponding services and credentials according to the configuration. The Certificate here is the credential model of the adapter and should not be understood as a TLS certificate file.

SMS and voice operations refer to the template configured in the cloud, and the parameters must comply with the template definition; the push must also be applied correctly and the target type is correct. A successful call usually means that the platform accepts the request, and delivery or business completion may be confirmed through subsequent queries, receipts, or callbacks. Avoid blindly applying universal retries to send operations.

Different Identities in WeChat

Application identification, user identification under the application, third-party platform tokens and payment merchant identities belong to different scopes. Applications cannot use identifiers from one scope directly to another scope, nor can they treat user authorization as merchant payment permissions.

The third-party platform process usually includes receiving platform tickets, obtaining platform access tokens, generating pre-authorization information, users completing authorization, saving and refreshing the authorizer credentials. The specific fields and duration are subject to the corresponding platform interface and current adapter implementation. The duration in the old README is not written as an immutable protocol.

The Callback Gateway Is Not an Automatic Signature Verifier

Currently both gateways expose the following dispatch entries:

gateway	Default POST route
Aliyun	/Externals/Aliyun/Fallback/{name}/{key?}
Wechat	/Externals/Wechat/Fallback/{name}/{key?}

name is the handler dispatch key, not the source authentication. The handler should verify the original data according to the specific service agreement, check the validity, and decrypt it if necessary before entering the business processing. WeChat Gateway also does not automatically provide the GET address verification required by all products.

Wechat can register the constructed handler with FallbackExecutor.Instance.Handlers during the startup phase; Aliyun's current plugin node is bound to the executor itself, and its Handlers attribute needs to be exposed before appending the collection. The complete registration fragments can be found at WeChat gateway and Alibaba Cloud Gateway respectively.

Callback Responses and Idempotent

The gateway hands over the request flow and parameters to the handler. The stream is only valid within the request lifecycle; when background processing is required, the necessary content should be copied and reliably saved within the size limit. The content returned by handler for non-empty results. The empty result is usually 204. This may not meet the confirmation format required by the server and must be verified according to the target protocol.

🚨 The gateway will not automatically complete signature verification, decryption and replay protection for all products. Callbacks may be repeated, and business updates should be deduplicated by verified event or transaction identifiers; receiving correct signatures does not mean that the same side effect can be executed multiple times.

First use desensitized fixed requests to verify signatures, error signatures, duplicates, expiration and processing failures, and then integrate the dedicated platform test environment. Logging requests associate identification and error types to avoid saving access keys, full signatures, certificate secrets, or raw transaction data.

Source references: Amazon, Aliyun, Wechat.

Continue Reading by Project

Aliyun · Amazon · Wechat