Refactor DirSync search process

[t2y]

I'm now developing an application to connect the Windows AD server and get entries. Thanks to #436, I can use DirSync() method to search. As my requirement, I have to handle several ten thousand entries. This is not so big, but waste of memory at once. I noticed #440 provides a search asynchronous feature, so I can search without getting all entries at once.

I looked into the code in DirSync() method and tested it. I refactored some minor changes for maintainability.

About DirSyncAsync() method

I made it as below. It works in my environment.

// DirSyncDirSyncAsync performs a search request and returns all search results
// asynchronously. This is efficient when the server returns lots of entries.
func (l *Conn) DirSyncAsync(
	ctx context.Context, searchRequest *SearchRequest, bufferSize int,
	flags, maxAttrCount int64, cookie []byte,
) Response {
	control := NewControlDirSyncForEncode(flags, maxAttrCount, cookie)
	searchRequest.Controls = append(searchRequest.Controls, control)
	r := newSearchResponse(l, bufferSize)
	r.start(ctx, searchRequest)
	return r
}

However, I can implement this by myself like this. So, what do you think about whether we provide this short-cut helper or not? I made this to confirm dirsync search works with asynchronous, so DirSyncAsync() method is not important for me.

control := NewControlDirSyncForEncode(flags, maxAttrCount, cookie)
searchRequest.Controls = append(searchRequest.Controls, control)
r := SearchAsync(ctx, searchRequest, 64)

[t2y]

I found a good name in RFC.

Controls sent by clients are termed 'request controls', and those sent by servers are termed 'response controls'.

https://datatracker.ietf.org/doc/html/rfc4511#section-4.1.11

[cpuschma]

Unfortunately, the function has been exposed in the latest release and is therefore considered immutable. I suggest an alias instead with the same function signature and add a mark to the current one to mark it as deprecated.

[t2y]

@cpuschma Could you review this? I don't have a strong opinion. I just want to confirm other opinions.

[t2y]

Is anyone interested in this PR? I'm glad to determine whether we provide DirSyncAsync or not.

[cpuschma]

No need to be passive aggressive. In the end this is an open source project where nobody gets paid for writing or reviewing code. I'm immensely happy about the PRs, I'm really, but I'd ask you to keep that in mind please.

Anyways, the PR looks good and moves the code to be more in line with the general design. Could you please address the comment regarding renaming the already exposed function?

[cpuschma]

Unfortunately, the function has been exposed in the latest release and is therefore considered immutable. I suggest an alias instead with the same function signature and add a mark to the current one to mark it as deprecated.

[t2y]

@cpuschma Welcome back! Thank you for your review. I added a migration function with the deprecated message.